Workstation Projects

Workstation Projects

Use the repository CLI as the source of truth for project checkout and local project audit behavior. Do not reimplement GitHub listing, clone paths, update logic, or dirty-repository checks in ad hoc scripts unless the CLI is missing the required capability.

References

Read only when needed:

• docs/guide/projects.md or docs/en/guide/projects.md for checkout policy and user-facing command examples.
• docs/guide/commands.md or docs/en/guide/commands.md for copyable setup commands.
• packages/cli/src/projects.ts for exact CLI behavior.
• projects.example.yaml for the manifest shape.

Workflow

1. Verify prerequisites before applying changes:

gh auth status
git config --global --get ghq.root

2. If ghq.root is missing and the task concerns normal workstation checkout, recommend or apply:

git config --global ghq.root ~/repos

3. Preview first. Use the repo script when working inside this repository:

pnpm projects:clone-active --limit 50

Use the built CLI outside the repo:

wst p active --limit 50

To target a different GitHub owner or organization, pass it as the target. The repo script already includes p active, so pass the owner directly after the script name:

pnpm projects:clone-active YunLeFun --limit 20
wst p active YunLeFun --limit 20

When the user wants to choose a subset by hand, use interactive selection:

wst p active --limit 50 -i

4. Apply only when the user clearly asks to clone/update, or after they approve the dry-run. Use --yes for writes:

wst p active --limit 50 --yes
wst p active YunLeFun --limit 20 --yes

5. For the active GitHub subset, update only when requested:

wst p active --limit 50 --update --yes

To pull every safe local checkout under ~/repos/github.com, review the colored plan and confirm in an interactive terminal:

workstation projects pull
workstation projects pull --dry-run
workstation projects pull --yes

The bulk pull skips repositories with uncommitted files, unpushed commits, stashes, detached HEADs, or missing/gone upstreams. It uses git pull --ff-only. Non-interactive runs remain preview-only unless --yes is present.

6. Before switching machines or cleaning up old checkouts, audit local Git repositories through the CLI:

wst p status

Use --check when a non-zero exit code should block a migration or cleanup:

wst p status --check

Use --all to include clean repositories. The audit scans down 6 directory levels by default; use --max-depth <number> for unusually deep or intentionally shallow checkout layouts:

wst p status --all
wst p status --max-depth 8

Safety Rules

• Keep clone commands defaulting to dry-run. Bulk pulls must preview before writes and require either interactive confirmation or --yes.
• Keep status/audit commands read-only.
• Prefer gh for GitHub authentication and repository discovery.
• Prefer ghq layout under ~/repos/github.com/<owner>/<repo>.
• Do not commit private or machine-specific repository names to this public repo.
• Do not expose private repository names in docs. In chat summaries, include only the detail needed for the user's current request.
• If gh, git, or network/auth fails, report the failing command and the next command the user should run; do not guess repository lists.
• Keep deterministic machine-state changes in CLI/scripts, not only in this skill.

Command Surface

Preferred commands:

workstation projects clone-active
workstation p active --limit 50
wst p active --limit 50
workstation projects pull
workstation projects pull --yes
wst p status
wst p status --check

Compatibility remains available:

dotfiles projects clone-active