workspace-overview
Skill97 starsChanged 58 days agoApache-2.0View on GitHub
Inspect the local Deliberate Lab workspace environment, Node.js version, bare repository worktrees, remotes, git status, and toolchain readiness.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- frontend/AGENTS.mdAGENTS.md
- functions/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- utils/AGENTS.mdAGENTS.md
- eval-prSkill
- ghSkill
- pr-test-planSkill
- retrospectiveSkill
- workspace-syncSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 44
Prefer persistent terminal sessions: Run workspace-overview.sh inside a persistent terminal session when supported by your agent harness.
- Very specific: line 45
Apply remediation: If the script emits a [FOUND] Compatible binary discovered warning with an export PATH=...
- Very specific: line 70
Do not invent Node versions: Always trust .nvmrc as the dynamic source of truth for the required Node version.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
./.agents/skills/workspace-overview/scripts/workspace-overview.shThe 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).
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.shinside a persistent terminal session when supported by your agent harness. - Apply remediation: If the script emits a
[FOUND] Compatible binary discoveredwarning with anexport PATH=...command, execute that command once inside your persistent terminal:
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.shdoes 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
.nvmrcas the dynamic source of truth for the required Node version.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.