Skip to content

setup.md

Latest commit

 

History

History
73 lines (53 loc) · 3.67 KB

setup.md

File metadata and controls

73 lines (53 loc) · 3.67 KB

Setup

If state/config.yaml doesn't exist, run ./setup. That script:

  • Detects their GitHub username via gh
  • Creates state/ directory with config and empty state files

After setup:

  1. Show the user the orgs list from state/config.yaml and ask which to keep. Update the file with their choices.
  2. Ask how far back to search for repos they've been active on (default: 3 months).
  3. Run ./discover-repos --since {date} and present repos with user-active for the user to pick which ones to track. Populate state/known_repos.yaml with their choices (all starting as status: unaudited).

Onboarding

This is someone's first time using the tool. Explain what's happening and why at each step during setup and first-session discovery:

  • Before running ./setup: Explain that this creates local config and state files. State persists between sessions on this machine but isn't synced anywhere by default.
  • Org selection: Explain that you scan their GitHub orgs for repos they've been active on, and they can trim the list to just the orgs they care about.
  • Repo discovery: Explain that you're looking at their recent GitHub activity to find repos they work on, and they'll pick which ones to start tracking. Repos start as "unaudited" — the initial audit is where you read every doc and verify it against the code.
  • After discovery: Give a brief overview of the session rhythm going forward: each session starts with a quick discovery check and weekly diff-based checks on already-audited repos, then offers to do a deep initial audit on one unaudited repo. At this point, setup is complete — the user can end the session whenever they want. The backlog of unaudited repos is saved to state and will be offered again at the start of future sessions. Initial audits are thorough and can be lengthy, so the user might prefer to tackle them in dedicated sessions rather than right now.
  • Permissions: Ask if the user wants to pre-approve the repo helper for git operations on cloned repos. This avoids repeated prompts during weekly checks. The permission pattern is Bash(./repo-tools:*). If they prefer tighter control, they can approve each command individually as it comes up.

State Sync (Optional)

By default, state is local to this machine. If the user wants to sync state across machines, they set it up themselves and create state/.sync.md with instructions for you to follow.

At the start of every session, check if state/.sync.md exists. If it does, read it and follow its instructions for session start. At the end of every session, follow its instructions for session end (if any).

If the user asks about syncing state across machines, list the examples in examples/*.sync.md and explain the trade-offs:

  • git-sync — Explicit pull/push, good conflict handling, requires a private repo. You can set this up for the user via gh repo create.
  • dropbox-sync — Automatic sync, no extra setup, but conflicts create duplicate files you clean up manually

If sync commands fail, warn the user but don't block the session.

File Formats

state/config.yaml

orgs:
  - my-org
  - another-org

state/known_repos.yaml

repos:
  - owner: someuser
    name: somerepo
    status: active
  - owner: someuser
    name: another-repo
    status: unaudited

state/verification.yaml

repos:
  somerepo:
    last_verified_date: "2025-01-15"
    last_commit_sha: "abc123"
    ignored_docs:
      - "docs/legacy-api.md"
    pending_findings:
      - doc: "docs/setup.md"
        description: "Missing instructions for Docker-based setup added in v2.3"
      - doc: "README.md"
        description: "CLI flags --verbose and --dry-run not documented"