git:20260929.3e33c69 to git:20260929.9c14215

# CLAUDE.md

This file provides guidance to Claude Code and other agent hosts when working with code in this repository.

```bash

bun install # install dependencies

bun run typegen # compile JSON Schemas to src/generated/

bun run build # bundle CLI into dist/index.js (ESM, Node >=22 target)

bun test # run unit and integration tests

node dist/index.js <command> # run built CLI via Node

```

## Architecture (v2)

Startidy is a contract-driven GitHub Stars organizer. It delegates planning, categorizing, and user interaction to the host agent while providing a deterministic, safe, and verifiable CLI for GitHub reads and writes.

```text

User ⇄ Host Agent / Skill

│ (reads snapshot, classifies repos, constructs plan.json)

▼

startidy CLI

│ (parses args, validates JSON Schema/policy, produces review.json, executes)

▼

core (pure domain logic: ports, snapshot, candidates, plan, policy, diff, executor)

▼

adapters (github-gh via `gh api`, file-store with account isolation & locking)

```

### Three-Phase Pipeline

1. **Read**:

- `startidy doctor --json`: Diagnoses Node, gh CLI, and GitHub authentication.

- `startidy snapshot --out snapshot.json --json`: Captures starred repos, user lists, memberships, and candidates.

- `startidy details --snapshot snapshot.json --candidates --offset 0 --limit 20 --out details.json --json`: Retrieves README contents in manageable batches.

2. **Plan & Review**:

- Agent formulates categories and decisions conforming to `src/schemas/plan.schema.json`.

- `startidy preview --snapshot snapshot.json --plan plan.json --out review.json --json`: Validates schema, references, scope, and policy; generates cryptographic digest and diff operations.

3. **Execution & Recovery**:

- `startidy apply --review review.json --json`: Executes verified operations against GitHub under an account lock.

- `startidy status --run <runId> --json`: Inspects execution journal.

- `startidy apply --resume <runId> --json`: Safely resumes partial executions without duplicating verified operations.

### Data Contracts

- `src/schemas/snapshot.schema.json`: Normalized user state, lists, repos, and candidates.

- `src/schemas/plan.schema.json`: Change intent (`bootstrap`, `incremental`, `targeted`, `full`).

- `src/schemas/review.schema.json`: Review binding plan, snapshot baseline, atomic operations, digest, and summary.

- Types in `src/generated/` are strictly generated via `bun run typegen`. Do not edit them by hand.