startidy git:20260929.896e78fA

Immutable. This exact content never changes and is served at /api/v1/blob/a4468921da2353b3.

---
name: startidy
description: Organize GitHub stars into User Lists using contract-driven workflows with startidy CLI.
---

# Startidy: GitHub Stars Organizer

Organize your starred repositories into structured GitHub User Lists safely and incrementally.
Startidy relies on the host agent for reasoning and classification, while the `startidy` CLI executes deterministic snapshots, previews, and operations.

## Prerequisites

1. Node.js >= 22.0.0
2. GitHub CLI (`gh`) authenticated with repository/user scopes (`gh auth login`)
3. `startidy` CLI installed globally (`npm install -g startidy`) or available locally

Run doctor diagnosis first:
```bash
startidy doctor --json
```

## Three-Phase Workflow

### Phase 1: Observation & Data Gathering

1. Capture full snapshot:
   ```bash
   startidy snapshot --out snapshot.json --json
   ```
2. Read `snapshot.json`. Inspect `account`, `totalStars`, existing `lists`, and `candidates`.
   - If this is a first run with pre-existing lists, respect existing memberships.
   - If running incrementally, focus strictly on candidate repositories (`snapshot.candidates`).
3. For candidate repositories where title and description are insufficient to classify, retrieve README details in batches:
   ```bash
   startidy details --snapshot snapshot.json --candidates --offset 0 --limit 20 --out details.json --json
   ```

### Phase 2: Category Planning & User Confirmation

1. Formulate categories following [classification.md](references/classification.md).
   - Prefer reusing established user lists.
   - Propose clear, descriptive names in the user's preferred language.
   - When evidence is inconclusive, choose `defer` rather than guessing.
2. Confirm taxonomy with the user:
   - Present proposed new lists, proposed assignments, and deferred items.
   - If the host provides an interactive question tool, use it; otherwise, ask directly in conversation and wait for the user's explicit reply.
3. Construct `plan.json` conforming to [plan-format.md](references/plan-format.md) and [plan.schema.json](references/plan.schema.json).
4. Generate the execution review:
   ```bash
   startidy preview --snapshot snapshot.json --plan plan.json --out review.json --json
   ```
5. Show the user the summary diff from `review.json`:
   - Number of lists to create, membership changes, deferred items, and exact lists affected.
   - Obtain user approval for this specific review.

### Phase 3: Verified Execution

1. Execute the approved review:
   ```bash
   startidy apply --review review.json --json
   ```
2. If execution halts due to network or rate limiting:
   ```bash
   startidy status --run <runId> --json
   startidy apply --resume <runId> --json
   ```
3. Report final organized counts and lists to the user.

## Command Reference & Plan Format

- [commands.md](references/commands.md): Full CLI flags and exit codes.
- [classification.md](references/classification.md): Principles for categorizing repositories.
- [plan-format.md](references/plan-format.md): Plan specification and JSON examples.