environment-observer

name	environment-observer
description	Perform heuristic environment discovery beyond basic directory listing. Check installed packages, analyze folder structure, inspect running processes, and assess system state. Use proactively when starting new tasks or when environment context is unclear.
allowed-tools	Execute, Read, Grep, Glob

Environment Observer

Apex2's heuristic environment observation phase implemented as a Claude Code skill. Goes far beyond simple ls to provide meaningful system context.

Instructions

When invoked, perform comprehensive environment discovery to understand the current state:

1. Package and Dependency Discovery

Identify what's available in the current environment:

# Python packages (if Python detected)
pip list | head -20
python -m pip list 2>/dev/null | head -20

# Node.js packages (if package.json detected)
npm list --depth=0 2>/dev/null
yarn list --depth=0 2>/dev/null

# System packages (distribution-specific)
dpkg -l | grep -E "(python|node|npm|git)" 2>/dev/null
rpm -qa | grep -E "(python|node|npm|git)" 2>/dev/null || brew list | grep -E "(python|node|npm|git)" 2>/dev/null

2. Folder and File Structure Analysis

Understand the project organization:

# Key configuration files
find . -regex ".*\.\(json\|yaml\|yml\|conf\|ini\|toml\|cfg\)" -type f | head -10

# Programming languages detected
find . -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.cpp" -o -name "*.go" -o -name "*.rb" -o -name "*.php" 2>/dev/null | head -20

# Documentation and setup files
find . -name "README*" -o -name "CHANGELOG*" -o -name "LICENSE*" -o -name "Makefile" -o -name "*.md" 2>/dev/null | head -10

# Test files
find . -name "*test*" -o -name "*spec*" -type f | head -10

3. Running Processes and Services

Check what's currently active:

# Python processes
ps aux | grep python | grep -v grep
ps aux | grep node | grep -v grep
ps aux | grep npm | grep -v grep

# Development servers
lsof -i :3000 -i :8000 -i :5000 -i :8080 2>/dev/null

# Database connections
ps aux | grep -E "(postgres|mysql|mongo|redis)" | grep -v grep

# Background services
systemctl list-units --type=service --state=running 2>/dev/null | head -10

4. System State and Resources

Assess available resources and constraints:

# Disk space
df -h

# Memory usage
free -h

# CPU info
nproc 2>/dev/null
cat /proc/cpuinfo | grep processor | wc -l 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null

# Network connectivity
ping -c 1 google.com 2>/dev/null | head -2  # Just check connectivity

# Current directory permissions
ls -la

5. Development Environment Context

Check for development tools and configurations:

# Version control status
git status 2>/dev/null
git branch --show-current 2>/dev/null

# Container presence (Docker, podman)
docker ps -a 2>/dev/null | head -5
podman ps -a 2>/dev/null | head -5

# Environment variables
printenv | grep -E "(PYTHON|NODE|JAVA|VIRTUAL)" | head -10

# Shell and terminal type
echo $SHELL
echo $TERM

6. Key File Content Discovery

Read selected critical files to understand project setup:

• package.json, requirements.txt, Cargo.toml (dependency info)
• .env.example, config/settings.py (configuration structure)
• README.md, CONTRIBUTING.md (project documentation)
• .gitignore (what's excluded from version control)

Analysis Process

1. Use Execute to run discovery commands safely
2. Use Read to examine critical files discovered
3. Use Grep to search for specific patterns in configuration files
4. Use Glob to find related files by pattern
5. Synthesize findings into comprehensive environment report

Output Format

Provide structured environment analysis:

Environment Context:

Development Stack:
  Primary Languages: [detected languages]
  Package Managers: [npm/pip/cargo/etc]
  Frameworks: [react/django/flask/etc]
  Testing Tools: [jest/pytest/cucumber/etc]

System Resources:
  CPU: [cores/info]
  Memory: [available/total]
  Disk: [free space on key partitions]
  Network: [connectivity status]

Active Services:
  Running: [list important services]
  Ports in use: [important port numbers]
  Processes: [development processes running]

Project Structure:
  Configuration files: [key config files found]
  Test organization: [test structure]
  Documentation: [available docs]
  Build tools: [make/webpack/etc]

Development Environment:
  Shell: [shell type]
  Containers: [docker/podman status]
  Version Control: [git status and branch]
  Environment Setup: [virtual env, nvm, etc.]

Key Findings:
  - [important observation 1]
  - [important observation 2]
  - [potential issue 1]
  - [recommendation 1]

Next Steps:
  - [action 1]
  - [action 2]

Discovery Categories

Python Projects

Look for: requirements.txt, pyproject.toml, setup.py, .venv/ or venv/ Check: Virtual environment activation, package versions, test framework

Node.js Projects

Look for: package.json, node_modules/, .nvmrc Check: Node version, npm vs yarn, development vs production deps

Containerized Projects

Look for: Dockerfile, docker-compose.yml, .dockerignore Check: Container status, image availability, port mappings

Multi-language Projects

Identify polyglot setups and integration points between different language components

When to Use

This observer is valuable when:

• Starting work in a new project
• Encountering unexpected behavior
• Debugging environment-related issues
• Planning deployment or testing
• Needing to understand project capabilities
• Setting up new开发 environment

The goal is to go beyond surface-level file listing to provide meaningful insights about what's actually available, running, and configured in the environment.