Guided Workspace Setup

Guided Workspace Setup

Overview

This skill installs and configures agent-fleet artifacts — skills, agent personas, commands or prompts, pi extensions and harnesses, references, and hooks — into a target workspace for a chosen coding agent. It runs interactively, writes project overrides to the target's .ai/agent-fleet-overrides.md, records what it installed in .ai/agent-fleet-setup.md, and can be re-run on the same workspace to add, update, or remove artifacts.

When to Use

• Onboarding a new project or workspace to agent-fleet
• Installing or changing which skills, commands, or personas a workspace uses
• Re-running setup to add, update, or remove already-installed artifacts
• Configuring a workspace's .ai/agent-fleet-overrides.md

NOT for: authoring new skills or personas (use designing-sub-agents); editing artifacts inside the agent-fleet repo itself; general context or rules-file tuning (use context-engineering).

The Workflow

This skill is run from the agent-fleet repo with the target coding agent active, and invoked with a path to the workspace to configure. Steps are gated — nothing is written to the target workspace until the user confirms in Step 9 — with one explicit exception: the pi-ask-user bootstrap in Step 5b. When the agent is pi and that interaction package is missing, the skill (after its own confirmation) installs it before the install menu and asks the user to reload and re-run, so the rest of setup can drive a native multi-select widget instead of a text fallback.

It maintains two files in the target's .ai/ directory: agent-fleet-overrides.md holds the minimal per-reader overrides that skills and the agent-hub harness read on every run/session start, and agent-fleet-setup.md holds the install record this skill itself reads on re-runs. The overrides file stays small; the install record absorbs the bulk.

1. Detect interaction capability

Determine which interaction mode this runtime supports. The mode is chosen by agent:

• claude-code → AskUserQuestion questionnaires (primary). Drive every Step 6 group through AskUserQuestion rather than printing a table and waiting for a free-text reply. Because the tool caps at 4 options per question and supports multiSelect: true, use this two-tier strategy:
• Quick path first. For each group, ask one AskUserQuestion (multiSelect off) offering Recommended set / Everything / Customise / Skip group. Only when the user picks Customise do you drill in. This avoids questionnaire fatigue on the ~20-item Skills group.
• Customise drill-in. Present the group's items as AskUserQuestion multiSelect prompts chunked by sub-category (the existing Group column), ≤ 4 options per question; a sub-category with > 4 items splits into sequential questions. Pre-selection still follows the Step 6 state rules (installed → pre-checked).

The selection semantics are identical to the tabular menu (unchecked installed item = remove, recommended adds ★ on top, etc.) — only the rendering differs.

• pi → native multi-select widget. Provided by the external pi-ask-user package; when it is absent, Step 5b bootstraps it first (install → reload → re-run) so this mode becomes available on the second pass. Because the Step 6 groups are large, prefer bootstrapping pi-ask-user over falling straight to the tabular fallback.
• opencode / any other runtime → native multi-select widget if supplied, else the tabular fallback below.
• Tabular fallback (any runtime lacking the above) — print the group table (Step 6 format) and ask the user to reply with the picks. Always accept the shortcuts all, recommended, none, or a comma-separated list of item names/numbers.

2. Resolve inputs

Resolve four things. Accept any already supplied in the invocation (the npx @chankov/agent-fleet init CLI passes the first three as flags); otherwise ask.

• Source root — the agent-fleet package. Resolution priority (use the first that works; never fall through silently):

1. Bootstrap marker — read /.ai/.agent-fleet-bootstrap.json if present. Its sourceRoot field is authoritative; the CLI wrote it during init and it points at the exact package the user's install came from (npm cache, global install, or symlinked clone). Verify the path still exists and contains a package.json whose name is @chankov/agent-fleet; if so, use it and stop. If the path no longer exists (e.g. npx cache was cleaned), warn the user and continue to step 2.
2. SKILL.md realpath — only if the marker is missing. If this SKILL.md is a symlink, follow it with readlink/realpath and use the resolved package root. Do not use the SKILL.md's workspace location (e.g. .pi/skills/guided-workspace-setup/) — bootstrap copies the file there, so that path is the workspace, not the source. The realpath only helps in symlink mode.
3. Ask the user explicitly. Print: "Source root not found. Run npx @chankov/agent-fleet@latest init to bootstrap, or paste an absolute path to the package." Verify the answer is a directory whose package.json#name is @chankov/agent-fleet. Do not scan the user's filesystem for other agent-fleet repos — that is invasive and produces wrong answers (it will pick up dev clones, forks, or stale copies).

The install record's ## install-status may also mention an older source root from a previous setup pass; ignore it for resolution. The bootstrap marker overrides it because it reflects what the user just ran. Note the divergence in the Step 9 summary so the user sees the change.

• Workspace path — the target project to configure. Confirm the path exists and is a directory; stop and ask again if it does not.
• Coding agent — claude-code, opencode, or pi. Detect the running agent from the runtime, show it to the user, and let them choose a different one.
• Package version — read version from the source root's package.json. This is the version that will be stamped into the install record in Step 10, and the right-hand side of every version-aware diff in Step 6.

3. Read the agent's setup conventions

For opencode and pi, read docs/-setup.md in the source root and follow the install locations and format it documents. For claude-code, use the built-in target map below. When the *-setup.md doc and the built-in map disagree, the doc wins.

Target map, relative to the workspace root:

| Artifact | claude-code | opencode | pi | |---|---|---|---| | Skills | .claude/skills// | per docs/opencode-setup.md | .pi/skills// | | Personas | .claude/agents/.md (generated) | .opencode/agent/.md (generated) | agents/.md | | Commands / prompts | .claude/commands/.md | .opencode/commands/af-.md | .pi/prompts/.md | | /orchestrate team config (companion of the orchestrate command) | .claude/orchestrate-teams.yaml | .opencode/orchestrate-teams.yaml | — | | References | .claude/references/.md | per docs/opencode-setup.md | per docs/pi-setup.md | | Hooks (claude-code only) | .claude/hooks/, registered in .claude/settings.json | — | — | | pi extensions | — | — | .pi/extensions// | | pi harnesses | — | — | .pi/harnesses// | | pi harness support | — | — | justfile (agent-fleet managed region), scripts/*.ts, .pi/agents/*.yaml, .pi/damage-control-rules.yaml, .pi/harnesses/package.json |

Personas are generated, not copied. The canonical persona format in agents/*.md is pi-flavored (agent-hub frontmatter: models, thinking, delegate_depth, subagents, …). For pi the file is installed as-is (copy or symlink). For claude-code and opencode the install runs the deterministic transformer instead — node /bin/cli.js transform-persona --agent --workspace — which translates tools/model to the target's vocabulary, adds mode: subagent for opencode, and drops the agent-hub-only keys. Never transform persona frontmatter by hand in this skill; the mapping lives in bin/lib/transform-persona.js, under test. Its --list flag prints the per-agent availability matrix (pi-only personas — bowser, web-debugger, orchestrator — are excluded for other agents and must not appear in their menu).

The pi harness support row is not a menu group of its own — it is the set of shared files the harnesses need in order to launch (the justfile recipes, the team-up script, the peer/team YAML, the damage-control rules, and the harness package.json of runtime deps). These travel with the pi harnesses group (Step 6, group 6): whenever any harness is installed, refreshed, or removed, this support set is refreshed from source in the same pass. The justfile specifically is refreshed from the current source, so retired-harness recipes are pruned and new-harness recipes added automatically — see Step 6 and Step 10 for the merge and removal rules.

When neither the built-in map nor the agent's *-setup.md defines a path for a selected artifact, ask the user instead of guessing.

4. Analyse the workspace

Scan the workspace to ground the recommendations and the overrides offer:

• Language, framework, and package manager (package.json, go.mod, pyproject.toml, …)
• Test runner and dev-server command, where discoverable
• Git presence and current branch
• Existing agent directories (.claude/, .opencode/, .pi/)
• Existing .ai/agent-fleet-setup.md — read its ## install-status section to learn what is already installed, and the version: line in ## workspace-summary to learn which package version performed the install
• An existing .ai/agent-fleet-setup.md (or any populated agent directory) means this workspace has prior state — flag it for Step 5

Version delta. Compare the recorded version: against the package version from Step 2:

• Missing version: → workspace is pre-versioning. Prompt the user: "This workspace was set up before agent-fleet used semver. Stamp it as v (assume installed copies match the current source), or wipe and reinstall?" Do not run the three-way diff for pre-versioning workspaces — there is no recorded baseline.
• Recorded version: equals current → no version-driven menu changes; Step 6 only surfaces content-level drift.
• Recorded version: differs from current → load CHANGELOG.md between the two versions, and load the .versions// snapshot from the source root. Both feed Step 6.

Report a short summary of the findings before continuing.

5. Doctor preflight (existing setup only)

If Step 4 found prior state — .ai/agent-fleet-setup.md exists or any of the install-target directories already contains skills/personas/commands — run the Doctor scan now, before showing the install menu. A fresh workspace skips this step.

Walk every install-target directory the chosen agent uses and look for broken symlinks — links whose source has been moved, renamed, or deleted. Directories to check, when present:

• agents/, .claude/agents/, .opencode/agent/, .opencode/agents/ (legacy), .pi/agents/
• .claude/skills/, .opencode/skills/, .pi/skills/, .agents/skills
• .claude/commands/, .opencode/commands/, .pi/prompts/
• .claude/references/, .claude/hooks/

For each broken link discovered:

1. Resolve where the link was pointing (readlink) and look up the canonical replacement in the source agents/ or skills/ tree — many breakages are stale names from the pre-merge layout (e.g. reviewer → code-reviewer, red-team → security-auditor).
2. If a canonical replacement exists, offer to repair it. For persona links under .claude/agents/ or .opencode/agent(s)/ the repair regenerates a transformed copy (transform-persona) — never a raw symlink into the source; everywhere else it repoints the symlink.
3. If no replacement exists, offer to delete the broken link.
4. Never overwrite a regular file you find at a target path — only act on symlinks whose target is missing.

Also flag any YAML configs (teams.yaml, peers.yaml) that still reference removed persona names, and offer to rename the references to the canonical name.

Also flag malformed peer entries in .pi/agents/peers.yaml: field lines (persona:, model:, ...) sitting under a team heading before any - name: ... list item — the team-up launcher's minimal parser silently drops them, so the peer never spawns. Advisory only: report with the missing - name: suggestion, never rewrite the file yourself. (agent-fleet doctor runs this same check.)

Also validate .ai/agent-fleet-overrides.md when it exists, against the schema in docs/agent-fleet-setup.md: unknown sections, unknown keys in known sections, invalid values for the mechanically parsed agent-hub keys (thinking.* levels, delegate-depth.*, persona-gate), rules: folders and docs: entry points that don't exist, and ## env required: names that are neither set nor declared in the root .env. These findings are advisory only — report them in the table with fix "edit by hand", never edit the overrides file yourself. (agent-fleet doctor runs this same validation.)

Present findings in a single table (keep it narrow — same widget constraint as Step 6/9: short Issue/Fix phrases, paths relative to the workspace, no overflowing cells):

| # | Path | Issue | Fix | |---|---|---|---| | 1 | .claude/agents/reviewer.md | broken link → missing reviewer.md | repoint → code-reviewer.md | | 2 | .pi/agents/red-team.md | broken link, no replacement | delete | | 3 | .pi/agents/teams.yaml | refs red-team | rename → security-auditor |

Then ask, multi-select: which fixes to apply now. Apply only the picked ones; record skipped items so the install menu can surface them again. Append a ## doctor-runs line to .ai/agent-fleet-setup.md with the date, agent, phase (preflight), and repaired / deleted / skipped counts.

The doctor scan is also exposed standalone as /doctor-agent-fleet — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.

5b. Bootstrap pi-ask-user first (pi only)

Skip this step entirely unless the agent is pi. For claude-code and opencode, the runtime already supplies a multi-select widget — go straight to Step 6.

For pi, the native multi-select widget comes from the external pi-ask-user package. The Step 6 groups are large (the Skills group alone is ~20 rows), so driving them through the tabular fallback is clumsy. The fix is to install the interaction tool before the menu, then re-enter setup once it is loaded.

From the Step 4 analysis, determine whether pi-ask-user is already available:

• Available — bundled by @chankov/agent-fleet, recorded as a project package in .pi/settings.json / pi list, or provided globally by user settings. Then this step is a no-op: note "interaction widget present" and proceed to Step 6, which will use the native widget.
• Not available — do the bootstrap:

1. Tell the user what is about to happen and why: "pi renders the setup menu best with the pi-ask-user widget. I'll install it project-scoped, then you reload and re-run setup so the rest of the menu uses real checkboxes."
2. Ask for confirmation (this is the one pre-Step-9 write, per the gating exception). If declined, fall back to the tabular mode and continue to Step 6 in this same pass — do not force the install.
3. On confirm, run pi install -l npm:pi-ask-user (project-scoped). Mention pi install npm:pi-ask-user only if the user explicitly wants a global pin.
4. Record the package under the external-pi-packages / project-packages line in .ai/agent-fleet-setup.md (same convention as Step 6's external-package handling) — do not copy files from node_modules.
5. Stop the pass here. Print: *"pi-ask-user installed. Reload pi (restart the session or /reload), t

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chankov
• Source: chankov/agent-fleet
• License: MIT

Install and usage instructions live in the source repository linked above.