# Junior Agent — setup for coding agents

The user wants you to install Junior and wire up bounded delegation. Complete this workflow in order. This document does not authorize paid model calls, commits, pushes, or destructive changes by itself; follow the human request and your environment permissions.

## 1. Establish the target and runtime

Use the project the user asked you to work on. If it is unknown, ask for its path before initializing it. Use Node.js 24 or newer, npm, and Git. On Windows use Ubuntu WSL for the Bash installer and worker execution. macOS and Linux can run it directly. Never use sudo or change authentication settings to work around an installation error.

## 2. Install the CLI

First check `junior --version`. Preserve a working installation unless an upgrade was requested.

Install from the open-source repository using the pinned source installer below. It checks out reviewed commit f8a551b15755a615866f4eaa65802fde80bb8ed6, installs locked dependencies, builds JavaScript, and installs the CLI using the active npm prefix. Requires Git and a local JavaScript build; no Rust is required.

Download and inspect the script before executing it:

```bash
curl -fsSL https://junioragent.dev/install.sh -o /tmp/junior-install.sh
cat /tmp/junior-install.sh
bash /tmp/junior-install.sh
junior --version
```

These URLs work once the site is deployed. When testing a local site, substitute its origin (for example `http://localhost:4321`) for `https://junioragent.dev`. Do not claim deployment or npm availability without verification.

If the npm prefix is not writable, report the error or use a user-owned prefix chosen by the user; do not escalate silently. `JUNIOR_INSTALL_DIR` and `JUNIOR_NPM_PREFIX` can select user-owned installation locations. Add the selected prefix's `bin` directory to PATH if needed. This installer does not set up your project, start a worker, or collect credentials.

## 3. Initialize the project and skills

Run inside the intended project, using its real path:

```bash
junior init --install --target both
```

This installs the delegation skill into `.agents/skills/junior/` for Codex and `.claude/skills/junior/` for Claude Code; choose `--target codex` or `--target claude` if appropriate. The skill and its CLI path manifest come from the installed package. Read the installed `SKILL.md` before delegation. The website also exposes a readable copy at `/skills/junior/SKILL.md`.

`--install` installs the tested Pi dependency when missing and downloads checksum-verified prebuilt FMECA, CPM, and Crossmatrix tools. Preserve existing configuration and customized skills. Do not add `--force`. A user-wide skill install requires explicit `--user`; for a Windows-hosted manager with a WSL worker use its actual accessible skill directory via `--skill-root`, with user authorization for that location. WSL defaults alone do not install into Windows user skill directories.

Inspect the JSON result. If a dependency or release is unavailable, report it and preserve completed setup; do not pretend all integrations are ready or compile Rust as a fallback. Optional TRIZ setup uses `--with-triz` only when requested and requires access to its release repository. Saved tool state is part of the handoff; installing binaries alone does not configure arbitrary global MCP clients.

Init writes configuration, an example task, and manager skills. Review these files with the user before committing; worktree delegation requires a clean source checkout. Do not automatically commit them without authorization.

## Coding agents and IDEs

Use AGENTS.md at the project root as the shared Junior entry point. After init, add or update exactly one managed block using the idempotency rules below:

```markdown
<junior>
For bounded deliverables, read .agents/skills/junior/SKILL.md and its CLI path manifest. Delegate through Junior with explicit scope, acceptance criteria, checks, and a budget. Enable jev.mode: enforce when frontier suitability must gate execution. Review the compact receipt and independent checks; return frontier_required or uncertain decisions to the manager. Never accept worker output automatically.
</junior>
```

Codex, Cursor editor/CLI, and agents that support AGENTS.md can use this entry point. Confirm the actual client's instruction discovery rather than assuming every IDE reads it. Claude Code keeps its installed .claude skill; if a shared entry point is needed, add a tagged pointer in CLAUDE.md. For Gemini CLI, use GEMINI.md; for GitHub Copilot in VS Code, Visual Studio, or JetBrains, use the client's supported repository instruction mechanism (commonly .github/copilot-instructions.md). Copilot CLI also supports AGENTS.md. For Windsurf, Cline, Roo Code, Aider, and other clients, consult that client's current rules/context mechanism and point it to AGENTS.md and the installed skill. Aider may need the file explicitly supplied as read-only context.

Keep any Markdown adapter minimal, inside one Junior block: “Read AGENTS.md and .agents/skills/junior/SKILL.md before delegating.” Do not duplicate the full workflow. Only configure the user's selected clients, preserve existing instructions, and verify the agent can read the skill and execute junior in the same runtime. An IDE alone does not supply terminal or provider access. Junior init installs skills; the setup agent performs the managed AGENTS.md/adapter step described here.

References: [Cursor CLI instructions](https://docs.cursor.com/en/cli/using), [Copilot CLI instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli), [Gemini CLI context](https://geminicli.com/docs/cli/gemini-md/).

## Idempotent shared manager instructions

If you add Junior-specific instructions to `AGENTS.md`, `CLAUDE.md`, or another shared Markdown instruction file, place all of that content inside exactly one managed block:

```markdown
<junior>
Use the installed Junior skill to delegate one bounded deliverable. Review its receipt and independent checks before accepting the work.
</junior>
```

On first installation, append the block without replacing existing content. On reruns, replace the existing block in place rather than appending another. Preserve every byte outside the block. If the desired content already matches, leave the file unchanged. If tags are duplicated, nested, or unbalanced, stop and report the conflict instead of guessing or overwriting user instructions. Do not add Junior text outside the tags. Remove only the managed block when uninstalling an authorized integration.

Use these tags for additions to shared prose instruction files, not inside JSON configuration. Dedicated skill files keep their required skill frontmatter and directory structure. Junior init currently installs separate skill files; it does not itself add AGENTS.md or CLAUDE.md blocks. Do not create extra instruction files merely to duplicate the skill.

## 4. Provider authentication — human step

Run `junior doctor`. If provider authentication or model setup is missing, ask the user to open `pi` in the same runtime and use `/login` and `/model`. Never ask the user to paste API keys into chat, log credentials, or change a working provider configuration without authorization. Authentication is required before live execution, but not for a mock handoff.

The current tested worker default is a DeepSeek commodity model via OpenRouter. Product copy is model-neutral; check installed defaults and supported providers rather than inventing configuration or promising that every model works identically.

## 5. Verify and hand back

Run `junior doctor` again and report execution readiness separately from optional integration readiness. Inspect the generated example contract before using it. For an offline smoke check, validate it and use the mock flag:

```bash
junior validate /absolute/project/tasks/example-task.json
junior handoff /absolute/project/tasks/example-task.json --mock
```

Replace the example path with the actual project path. Do not dispatch a paid live task until the user authorizes it. Before real work, specify one deliverable, scope, acceptance criteria, independent checks, and a budget. Follow the installed skill's review rules: ready_for_review means manager review is required, not automatic acceptance.

Finish with a compact setup receipt: CLI version and location, project, installed skill paths, doctor findings, mock outcome if run, and anything requiring the user's attention. Do not stop after installing the CLI without checking the project setup and readiness.

## Frontier suitability gate

Set jev.mode to enforce in a deliverable contract to require classification before execution. A frontier_required, unclear, or uncertain result returns needs_review without starting the commodity worker. Inspect the compact receipt attention decision, reason, and probability; the manager clarifies, re-scopes, or takes over. Shadow mode is advisory and the default is off. Junior does not automatically invoke a frontier model.