agent-onboarding

agent-onboarding

Turn any repo into a self-improving agent environment.

---

Quick Install

1. Install the plugin

claude plugin marketplace add namelesstherebel/agent-onboarding && claude plugin install agent-onboarding

2. Confirm it is installed

claude plugin list

You should see agent-onboarding with status installed. If it is not listed, re-run the install command above.

3. Run onboarding

Open Claude Code in the repo you want to set up. If *onboard works, use it. If Claude doesn't recognize it, paste this prompt:

Run the agent-onboarding workflow. Read the plugin's commands*onboard.md and execute the full 7-phase onboarding process for this repository.

---

What It Does

Onboarding workflow — a 7-phase guided process that interviews you about your project and produces CLAUDE.md, INTENT.md, PROJECT_BRIEF.md, SPEC_INVENTORY.md, and a full SPECS/ directory.

Works on greenfield projects and existing codebases — for existing repos, it runs a 3-stage pre-analysis (structural scan → convention extraction → pattern mining) before asking a single question. It leads with what it found.

Self-improving runtime — installed into your repo during onboarding. It tracks friction during tasks (gaps in specs, missing context, unclear intent, backtracking), logs errors, audits context hygiene, and generates improvement proposals into IMPROVEMENT_QUEUE.md. You review proposals with *review. Approved changes get merged back into the affected artifacts, incrementing their version.

Context best practices built in — the plugin enforces lean context engineering: CLAUDE.md stays under 200 lines with universal rules only, conditional instructions go in .claude/rules/ with glob patterns (zero context cost when inactive), formatting rules stay in tooling, and the self-improvement loop prunes stale instructions alongside adding new ones. Token budget targets are built into the workflow.

Decision log — onboarding produces CONTEXT/decisions.md, an append-only log of architectural and convention decisions with rationale. The "why" behind choices is the context most vulnerable to loss. It is never summarized or pruned.

Git worktree support — optional Phase 5F walks you through setting up behavior profiles for worktrees. Each profile gets its own CLAUDE.md and INTENT.md as pure behavioral contracts (project-agnostic, reusable across repos). A WORKTREES.md at root documents the profiles, branch naming patterns, usage commands, and the full inheritance chain.

---

Commands

These are star commands. Type them in Claude Code once the plugin is installed.

Command	What it does
*onboard	Start or resume the 7-phase onboarding workflow
*review	Surface pending improvement proposals for approval/rejection
*reflect	Manually trigger a friction review, proposal generation, and context reconciliation
*status	Report environment health: spec coverage, open proposals, last activity

Star commands work because the plugin provides a CLAUDE.md that Claude Code loads into context. If *onboard doesn't fire immediately, use the fallback prompt above — it produces the same result.

---

Setup Guide

Install the plugin

claude plugin marketplace add namelesstherebel/agent-onboarding && claude plugin install agent-onboarding

To reinstall after an update:

claude plugin marketplace remove agent-onboarding
claude plugin marketplace add namelesstherebel/agent-onboarding
claude plugin install agent-onboarding

Verify installation

Run claude plugin list in your terminal and confirm agent-onboarding appears with status installed.

Run onboarding

Open Claude Code in your target repo and type *onboard. The agent reads your codebase first, then walks you through 7 phases. Use these signals at any point to control the flow:

Signal	Action
ready or next	Advance to the next phase
skip	Accept placeholders and advance
pause	Save progress and stop cleanly
back	Return to the previous phase

After onboarding, your repo will contain: