Before handing a workspace to anyone - client, team member, collaborator - I run this checklist. A leaked secret in a markdown file isn’t just embarrassing; AI agents treat every file as authoritative context, which means a stale credential in a doc can become an attack surface the moment someone runs an agent over it.

Every item must pass.

Security

  • No secrets in any file: grep -r "ghp_\|xoxb-\|sk-\|ntn_\|secret_\|Bearer " . --include="*.md" --include="*.json" --include="*.yaml" returns nothing
  • No .env files with real values: All .env files contain only placeholders or are listed in .gitignore
  • No OAuth tokens: ~/.google_workspace_mcp/ or similar credential directories are NOT included
  • No personal API keys: Check all config files and templates for leaked keys

Paths

  • No hardcoded absolute paths: grep -r "/Users/" . --include="*.md" --include="*.json" --include="*.yaml" --include="*.sh" returns nothing
  • No machine-specific paths: No references to specific home directories, iCloud paths, or nvm versions
  • All paths use relative references or documented placeholders ({WORKSPACE_ROOT})
  • Cross-repo paths use CLAUDE.md: Agents read Project Locations table, not hardcoded paths

Agent Templates

  • All agents in manifest.json exist: Every file referenced in manifest.json exists in agent-library/
  • Manifest is valid JSON: python3 -c "import json; json.load(open('agent-library/manifest.json'))"
  • Agent frontmatter is valid: Each .md file has --- delimited YAML frontmatter with name, description, model, color
  • No operator-specific references: Agents don’t reference specific project names, people, or companies
  • Agents read CLAUDE.md dynamically: Project discovery happens by reading CLAUDE.md, not from hardcoded tables

MCP Guides

  • All referenced guides exist: Every guide mentioned in mcp-guides/README.md exists
  • Guides use placeholder values: Tokens show as your_token_here, paths show as /full/path/to/command
  • Prerequisites are documented: prerequisites.md covers all needed software

Workspace Structure

  • CLAUDE.md is complete: Has Project Portfolio, Agents table, MCP Integrations, Session Logging instructions
  • Temp log directories exist: logs/temp/ and logs/archive/ with .gitkeep
  • Session log structure: Each project folder has {project}-status.md, {project}-session-log.md, {project}-goals.md
  • .gitignore is appropriate: Excludes .env, credentials, node_modules, archive directories
  • No empty directories without .gitkeep: Git tracks files, not directories

Documentation

  • README is accurate: Describes what the workspace is and how to get started
  • Onboarding agent works end-to-end: Run through the full onboarding flow in a test
  • MCP guides are followable: A non-technical person can follow each guide without getting stuck

Quick Automated Checks

Run these commands from the workspace root:

# Check for secrets
grep -rn "ghp_\|xoxb-\|sk-\|ntn_\|secret_\|Bearer " . \
  --include="*.md" --include="*.json" --include="*.yaml" \
  --include="*.py" --include="*.sh" \
  | grep -v "your_.*_here\|placeholder\|example"

# Check for hardcoded paths
grep -rn "/Users/" . --include="*.md" --include="*.json" \
  --include="*.yaml" --include="*.sh"

# Validate manifest
python3 -c "import json; d=json.load(open('agent-library/manifest.json')); \
  [print(f'  {a}: {d[\"agents\"][a][\"file\"]}') for a in d['agents']]"

# Check agent files exist
python3 -c "
import json, os
m = json.load(open('agent-library/manifest.json'))
for name, info in m['agents'].items():
    path = f'agent-library/{info[\"file\"]}'
    status = 'OK' if os.path.exists(path) else 'MISSING'
    print(f'  [{status}] {name}: {path}')
"