vc:setup

# VibeCo Agent Harness Setup

Interactive setup for the agent development harness. Works on fresh projects and existing projects with pre-existing `.claude/` or `process/` configs.

The skill adapts its flow based on what it finds:
- **New projects** (no existing process/ or context): detect, ask the user about their project, scaffold, study, validate.
- **Existing projects** (has process/, context files, or CLAUDE.md): detect, study what exists first, present findings and ask what to keep vs change, scaffold with approval, re-study to fill gaps, validate.

In both cases, the skill asks questions and waits for approval at every major step. It never silently reorganizes files or overwrites good content.

CLAUDE.md and AGENTS.md are managed protocol files (orchestrator, RIPER-5 methodology, routing). They contain zero project-specific content and should NOT be adapted. Project-specific information lives in `process/context/all-context.md`, which is populated during the STUDY phase.

## Prerequisites

- The target repo should have a `package.json` (or equivalent project manifest).
- That's it. The skill handles the rest.

## Workflow

Read `references/vc-setup.md` for detailed phase instructions, detection heuristics, interactive question templates, parallel subagent delegation strategy, and validation checks.

### Phase 0: BOOTSTRAP (handled by install.sh)

The `install.sh` script handles fetching and installing harness files before vc-setup runs. For existing projects, it backs up old `.claude/`, `.codex/`, `.agents/` to `.vibecode-backup/`, then does a clean install of all kit files. User's `.claude/settings.json` is restored after install. The `process/` directory is never touched by install.sh -- layout migration happens in vc-setup's SCAFFOLD phase.

**If harness files are already present** (`.claude/agents/` and `.claude/skills/` exist with 12+ agents and 20+ skills), skip Phase 0 and proceed directly to Phase 1 DETECT.

**If harness files are NOT present**, tell the user to run the installer first:
```
curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash
```

Then re-run vc-setup.

### Phase 1: DETECT

Gather information about the target project before making any changes.

1. Read `package.json` to detect the package manager (`packageManager` field, lockfile presence), framework (dependencies), and test commands (scripts).
2. Detect monorepo structure: `workspaces` in `package.json`, `pnpm-workspace.yaml`, `apps/`, `packages/` directories.
3. Scan for existing `process/`, `docs/`, `.github/` directories and any context files.
4. **Classify the project** as one of:
   - **New**: no existing `process/` directory, no `all-context.md`, no meaningful prior setup.
   - **Existing**: has `process/`, `all-context.md`, CLAUDE.md with project content, or other prior context.
5. Present a detection summary to the user and wait for confirmation before proceeding.

**After detection, the workflow branches based on project type.** See the two flows below.

---

### Flow A: New Project (no existing process/ or context)

For projects where the harness is being set up for the first time.

**Step 1: ASK** -- Before scaffolding or scanning anything, have a real conversation with the user about their project. Do not guess when you can ask. Do not ask a fixed list of questions and move on — this is an open-ended discovery conversation that continues until you have a thorough understanding.

Start with the basics, then follow up based on their answers:

**Round 1 — Project identity:**
- "What is this project? Give me a brief description in your own words."
- "Who uses it? Who is the target audience?"

**Round 2 — Architecture and scope** (adapt based on Round 1 answers):
- "What are the main product areas or features?"
- "How is the codebase organized? Any key services, packages, or modules I should know about?"
- "What are the most important or complex parts of the codebase?"

**Round 3 — Workflow and conventions** (adapt based on what you've learned):
- "Do you work solo or with a team?"
- "Any coding conventions, naming patterns, or architectural decisions that are important?"
- "How do you handle testing? CI/CD? Deployments?"
- "Any external services, APIs, or integrations that are central to the project?"

**Round 4 — Follow-ups** (ask as many as needed until everything is clear):
- Follow up on anything vague or interesting from previous answers.
- "You mentioned [X] — can you tell me more about how that works?"
- "Are there any pain points, tech debt, or things you want agents to be careful about?"
- "Anything else that is important context for working on this codebase?"

**Keep asking follow-ups until you genuinely understand the project.** If the user gives a short answer, probe deeper. If they mention something complex, ask for details. The goal is that after this conversation, you could explain the project to another developer — what it does, how it's built, what matters, and what to watch out for. Only move on when both you and the user are satisfied.

**Step 2: SCAFFOLD** -- Create the `process/` directory structure from seed templates. (See Phase 2 details below.)

**Step 3: STUDY** -- Deep-scan the codebase and populate context files with real content, enriched by the user's answers from Step 1. (See Phase 3 details below.)

**Step 4: VALIDATE** -- Verify everything is wired correctly. (See Phase 4 details below.)

---

### Flow B: Existing Project (has process/, context files, or prior setup)

For projects that already have some form of process/ directory, context files, or CLAUDE.md content.

**Step 1: STUDY EXISTING** -- Before proposing any changes, read and understand what is already there:

- Read all files under `process/context/` (especially `all-context.md`).
- Read all files under `process/general-plans/` and `process/features/`.
- Read the existing CLAUDE.md if it contains project-specific content (beyond the managed protocol).
- Re