PAIR-code/deliberate-lab / .agents/skills/workspace-overview
workspace-overview
VerifiedInspect the local Deliberate Lab workspace environment, Node.js version, bare repository worktrees, remotes, git status, and toolchain readiness.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| scripts/workspace-overview.shexecutable | script | 12.4 KB |
SKILL.md
View on GitHub---
name: workspace-overview
description: >
Inspect the local Deliberate Lab workspace environment, Node.js version,
bare repository worktrees, remotes, git status, and toolchain readiness.
---
# Workspace Overview
Ground an AI agent or developer in Deliberate Lab's local development environment. This skill inspects Node.js against `.nvmrc`, discovers installed runtimes, surveys the bare repository and sibling worktree topology, checks GitHub CLI auth, and verifies monorepo build artifacts.
## When to use
Invoke this skill when:
- Starting a new coding or pairing session.
- Entering the repository workspace for the first time.
- Verifying whether Node.js matches the version required by `.nvmrc`.
- Getting an overview of existing worktrees, branches, and uncommitted edits.
- Diagnosing missing build artifacts (`utils/dist`) or toolchain issues.
Trigger phrases:
- "Orient to workspace"
- "Check environment"
- "Run workspace overview"
- "Check setup"
- "Where am I in the repo?"
## Procedure
### 1. Run the Diagnostic Script
From any worktree directory or the parent repository container, execute:
```sh
./.agents/skills/workspace-overview/scripts/workspace-overview.sh
```
The script visibly echoes the underlying diagnostic commands (`git`, `gh`, etc.) as it runs, providing complete transparency into command provenance and worktree topology. In repositories with dozens of worktrees or branches, if the diagnostic output exceeds 7 KB, it automatically saves to a temporary file via `mktemp` and provides the path for lossless inspection via `view_file` ([ADR 0003](../../decisions/0003-agent-tooling-output-standards.md)).
### 2. Establish Node.js in Persistent Terminal Sessions
Deliberate Lab requires the Node.js major version specified in `.nvmrc` (v22). Non-interactive agent subshells often lack shell initialization or inherit a mismatched host version.
- **Prefer persistent terminal sessions**: Run `workspace-overview.sh` inside a persistent terminal session when supported by your agent harness.
- **Apply remediation**: If the script emits a `[FOUND] Compatible binary discovered` warning with an `export PATH=...` command, execute that command once inside your persistent terminal:
```sh
export PATH="<path-to-discovered-node-bin>:$PATH"
```
Once exported in the persistent session, all subsequent commands (`npm test`, `npm run build`, `npm start`) will automatically inherit the correct Node runtime.
### 3. Act on Diagnostic Warnings
| Section | Diagnostic Warning | Recommended Action |
| :--- | :--- | :--- |
| **Node.js** | Missing / not found in `$PATH` | Apply the emitted `export PATH="...:$PATH"` from Tier 2 discovery. If uninstalled, run `nvm install <version>`. |
| **Node.js** | Major version mismatch | Export the path to the matching Node binary discovered in NVM or install via NVM. |
| **Worktree** | Uncommitted file(s) | Review `git status --short` before switching branches or pulling upstream changes. |
| **Toolchain** | `gh` not authenticated | Run `gh auth login` or verify credentials if PR/issue interactions fail. |
| **Toolchain** | `gh` auth timed out | Keyring locked or waiting for desktop prompt. Unlock desktop session or check for modal, then re-run. |
| **Toolchain** | `gh` default repo not set | Run `gh repo set-default PAIR-code/deliberate-lab` to resolve multi-remote ambiguity. |
| **Artifacts** | `node_modules` missing | Run `npm ci` from the worktree root. |
| **Artifacts** | `utils/dist` missing or empty | Run `npm run build -w utils`. `utils` is the shared dependency for `functions` and `frontend`. |
| **Artifacts** | `functions/lib` missing | Run `npm run build -w functions` if running backend tests or the Firebase emulator. |
## Safety Rules
- **Read-only by design**: `workspace-overview.sh` does not modify git refs, switch branches, or alter code. It is safe to run unconditionally at any time.
- **Do not invent Node versions**: Always trust `.nvmrc` as the dynamic source of truth for the required Node version.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |