| name | workspace-surface-audit |
| tier | companion |
| description | Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Audits the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommends the highest-value continuous-improvement-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their environment. |
| origin | continuous-improvement |
Workspace Surface Audit
Read-only audit skill for answering the question "what can this workspace and machine actually do right now, and what should we add or enable next?"
This is the continuous-improvement answer to setup-audit plugins. It does not modify files unless the user explicitly asks for follow-up implementation.
When to Use
- User says "set up Claude Code", "recommend automations", "what plugins or MCPs should I use?", or "what am I missing?"
- Auditing a machine or repo before installing more skills, hooks, or connectors
- Comparing official marketplace plugins against continuous-improvement coverage
- Reviewing
.env, .mcp.json, plugin settings, or connected-app surfaces to find missing workflow layers
- Deciding whether a capability should be a skill, hook, agent, MCP, or external connector
Non-Negotiable Rules
- Never print secret values. Surface only provider names, capability names, file paths, and whether a key or config exists.
- Prefer continuous-improvement workflows over generic "install another plugin" advice when continuous-improvement can reasonably own the surface.
- Treat external plugins as benchmarks and inspiration, not authoritative product boundaries.
- Separate three things clearly:
- already available now
- available but not wrapped well in continuous-improvement
- not available and would require a new integration
Audit Inputs
Inspect only the files and settings needed to answer the question well:
- Repo surface
package.json, lockfiles, language markers, framework config, README.md.mcp.json, .lsp.json, .claude/settings*.json, .codex/*AGENTS.md, CLAUDE.md, install manifests, hook configs
- Environment surface
.env* files in the active repo and obvious adjacent continuous-improvement workspaces- Surface only key names such as
STRIPE_API_KEY, TWILIO_AUTH_TOKEN, FAL_KEY
- Connected tool surface
- Installed plugins, enabled connectors, MCP servers, LSPs, and app integrations
- continuous-improvement surface
- Existing skills, commands, hooks, agents, and install modules that already cover the need
Audit Process
Phase 1: Inventory What Exists
Produce a compact inventory:
- active harness targets
- installed plugins and connected apps
- configured MCP servers
- configured LSP servers
- env-backed services implied by key names
- existing continuous-improvement skills already relevant to the workspace
If a surface exists only as a primitive, call that out. Example:
- "Stripe is available via connected app, but continuous-improvement lacks a billing-operator skill"
- "Google Drive is connected, but there is no continuous-improvement-native Google Workspace operator workflow"
Environment Grain
Before any tool-class advice, capture the per-host facts that make commands either run or fail. The 28-day usage report's recurring "command failed / wrong approach" friction class roots almost entirely in this grain being unrecorded at session start — the agent reaches for jq, finds it missing, retries; reaches for bash chaining, hits PowerShell parser errors, retries; trusts a stale pwd after tsc, runs verification from the wrong directory, retries.
Probe and record (no destructive commands; quote results inline):
- Shell flavor.
echo $SHELL on POSIX or $PSVersionTable.PSEdition on Windows; detect bash, zsh, pwsh, or cmd. PowerShell on Windows treats &&, 2>&1, and quoting differently from bash; Git Bash on Windows is bash-shaped but lacks several POSIX utilities by default.
- OS family + line endings.
uname -s (or PowerShell $IsWindows) plus git config --get core.autocrlf. On Windows with core.autocrlf=true, git status reports phantom modifications on every checked-out file — git diff --stat is the reliable change-set view.
- jq availability.
command -v jq (or Get-Command jq). When jq is missing, observation-pipeline hooks fall back to a thin schema and curl/JSON one-liners need a node/python rewrite.
- Case-sensitive filesystem. Test by creating two paths differing only in case in a tempdir. NTFS (Windows) and APFS (macOS default) are case-insensitive; Linux ext4 and case-sensitive APFS are case-sensitive. Affects
CLAUDE.md vs claude.md resolution and import paths.
- CWD baseline.
pwd (or Get-Location) recorded at session start. tsc, build scripts, and some test runners change CWD as a side effect; subsequent commands run from the wrong directory return "deps not installed" or "config not found" misreads.
- Parallel-actor expectation. Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the
gateguard Parallel-Actor Gate runs bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh" (source: scripts/git-state-snapshot.sh) to produce a single JSON envelope ({head, upstream, dirty, root, branch}) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
Output the recorded grain as a single fenced block so it survives context compaction and any later phase can reference it without re-probing:
shell-flavor: pwsh
os: windows-11 / autocrlf=true
jq: missing
case-sensitive: false
cwd-baseline: D:/Ai/continuous-improvement
parallel-actor: yes
The fenced block is the contract surface — keep the field names stable so downstream skills (gateguard, verification-loop, future autonomous-release-train) can parse it without per-host special-casing.
Phase 2: Benchmark Against Official and Installed Surfaces
Compare the workspace against:
- official Claude plugins that overlap with setup, review, docs, design, or workflow quality
- locally installed plugins in Claude or Codex
- the user's currently connected app surfaces
Do not just list names. For each comparison, answer:
- what they actually do
- whether continuous-improvement already has parity
- whether continuous-improvement only has primitives
- whether continuous-improvement is missing the workflow entirely
Phase 3: Turn Gaps Into continuous-improvement Decisions
For every real gap, recommend the correct continuous-improvement-native shape:
| Gap Type | Preferred continuous-improvement Shape |
|---|
| Repeatable operator workflow | Skill |
| Automatic enforcement or side-effect | Hook |
| Specialized delegated role | Agent |
| External tool bridge | MCP server or connector |
| Install/bootstrap guidance | Setup or audit skill |
Default to user-facing skills that orchestrate existing tools when the need is operational rather than infrastructural.
Output Format
Return five sections in this order:
- Current surface — what is already usable right now
- Parity — where continuous-improvement already matches or exceeds the benchmark
- Primitive-only gaps — tools exist, but continuous-improvement lacks a clean operator skill
- Missing integrations — capability not available yet
- Top 3-5 next moves — concrete continuous-improvement-native additions, ordered by impact
Recommendation Rules
- Recommend at most 1-2 highest-value ideas per category.
- Favor skills with obvious user intent and business value:
- setup audit
- billing/customer ops
- issue/program ops
- Google Workspace ops
- deployment/ops control
- If a connector is company-specific, recommend it only when it is genuinely available or clearly useful to the user's workflow.
- If continuous-improvement already has a strong primitive, propose a wrapper skill instead of inventing a brand-new subsystem.
Good Outcomes
- The user can immediately see what is connected, what is missing, and what continuous-improvement should own next.
- Recommendations are specific enough to implement in the repo without another discovery pass.
- The final answer is organized around workflows, not API brands.
