vc-setup

# VibeCo Agent Harness Setup

> **CRITICAL — Dual-File Synchronization:** This document and `references/vc-setup.md` must be edited together. Any change to Merge Mode logic, safe-inference rules, or migration flow MUST appear in both files in the same commit. Dual-file drift creates inconsistent user behavior.

> **Output style:** Use BLUF (answer first), plain language, no unexplained jargon, TL;DR on long responses. Full rules in `process/development-protocols/communication-standards.md` once installed — on first run that file may not exist yet, so follow this inline rule instead.

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 project manifest. Detection order:
  1. `package.json` — Node/Bun/Deno projects (JS/TS)
  2. `pyproject.toml` or `requirements.txt` — Python projects
  3. `go.mod` — Go projects
  4. `Gemfile` — Ruby projects
  5. `Cargo.toml` — Rust projects
  6. None found — ask the user: "What language/runtime does this project use? I'll adapt the setup to match."
- 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.

**What install.sh DOES create under `process/`:** `process/_seeds/`, `process/development-protocols/`, and `process/context/generated-skills-catalog.json`. These are kit-installed files, not user content.

**What install.sh does NOT create:** `process/general-plans/`, `process/features/`, `process/context/all-context.md`, or any context group directories. Those are vc-setup's job, created during the SCAFFOLD and STUDY phases.

**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. **Non-JS projects:** if the detected manifest is NOT `package.json` (e.g. `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`), SKIP the Package Manager / Framework / Test-Setup detection steps below and jump to Manifest Detection in `references/vc-setup.md` §DETECT Phase.
2. Read `package.json` to detect the package manager (`packageManager` field, lockfile presence), framework (dependencies), and test commands (scripts).
3. Detect monorepo structure: `workspaces` in `package.json`, `pnpm-workspace.yaml`, `apps/`, `packages/` directories.
4. Scan for existing `process/`, `docs/`, `.github/` directories and any context files.
5. **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.

   **Classification corner cases (full 7-row table in `references/vc-setup.md` §Project Classification):**
   - `process/` contains ONLY kit-installed files (`_seeds/`, `development-protocols/`, `context/generated-skills-catalog.json`) and no user content → **New / Flow A** (install.sh ran but the user hasn't set up yet).
   - `all-context.md` exists but its non-comment body is all placeholder/stub (`<!-- STUDY: -->`) → **Flow A**, continue to STUDY (do NOT treat as existing project).
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 le