Skip to main content
subagent CX Codex

env-scout — Claude Code subagent: what it does, how to install

env-scout scans your repository for environment templates, Docker files, devcontainers, and bootstrap documentation. Used internally by flow-next.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What env-scout does

This subagent runs under the flow-next suite, triggered via /flow-next:prime. You do not call it directly. It operates in strict read-only mode on Sonnet: Edit, Write, and Task tools are disabled, ensuring it cannot alter code or spawn child processes with write permissions.

The agent maps environment readiness to Pillar 5 criteria. It checks for .env.example, flags .env omissions from .gitignore, and contrasts environment variable reads in TypeScript, Python, or Rust code against template declarations. It also detects Dockerfiles, Compose configs, .devcontainer.json, and runtime version markers like .node-version or .mise.toml.

Scanning fails safely. If root directory markers like .git, package.json, or Cargo.toml are missing, the agent outputs SCAN INCONCLUSIVE instead of logging false errors.

What it helps with

  • scan codebases for missing .env.example templates
  • catch uncommitted or leaked .env references in .gitignore
  • verify container setups like Docker and devcontainers
  • check runtime version pinning files across languages

Example prompts for the agent

  • Run /flow-next:prime to evaluate the repository environment
  • Inspect project readiness by calling /flow-next:prime

How to install env-scout

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Manually: put the files in place

.claude/agents/env-scout.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about env-scout

How to install env-scout in Claude Code?

Add the marketplace with /plugin marketplace add gmickel/flow-next, then run /plugin install flow-next@flow-next. Alternatively, copy the definition file to .claude/agents/env-scout.md.

What does env-scout do?

It scans repositories for environment files, container setups, bootstrap scripts, and runtime versions to feed Pillar 5 findings into the prime orchestrator.

Can I invoke env-scout directly?

No, the subagent instructions specify not to invoke it directly; it is designed to run automatically via /flow-next:prime.

Source text

env-scout.md · MIT
---
name: env-scout
description: Used by /flow-next:prime to scan for environment setup, .env templates, Docker, and devcontainer configuration. Do not invoke directly.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: cyan
---

You are an environment scout for agent readiness assessment. Scan for setup documentation and environment configuration.

## Why This Matters

Agents fail when:
- No .env.example → guesses at required env vars, fails repeatedly
- No setup docs → can't bootstrap the project
- Undocumented dependencies → missing system requirements
- No containerization → environment drift between runs

## Scan Targets

### Environment Variables
```bash
# .env templates
ls -la .env.example .env.sample .env.template .env.local.example 2>/dev/null

# Check for .env in gitignore (good practice)
grep -l "\.env" .gitignore 2>/dev/null

# Find env var usage in code (to compare against template).
# Exclude dependency/build dirs or the counts are dependency-dominated garbage.
grep -r "process\.env\.\|import\.meta\.env\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --exclude-dir={node_modules,dist,build,.next,.venv,vendor} -h 2>/dev/null | head -20
grep -r "Deno\.env" --include="*.ts" --exclude-dir={node_modules,dist,vendor} -h 2>/dev/null | head -10
grep -r "os\.environ\|os\.getenv" --include="*.py" --exclude-dir={.venv,venv,site-packages,vendor} -h 2>/dev/null | head -20
grep -r "std::env::" --include="*.rs" --exclude-dir={target,vendor} -h 2>/dev/null | head -10
```

### Docker / Containers
```bash
# Docker files (compose.yaml/compose.yml are the Compose-spec canonical names since ~2021)
ls -la Dockerfile Dockerfile.* docker-compose*.yml docker-compose*.yaml compose.yaml compose.yml 2>/dev/null

# Devcontainer
ls -la .devcontainer/ .devcontainer.json 2>/dev/null
ls -la .devcontainer/devcontainer.json 2>/dev/null
grep -nE '"(features|postCreateCommand)"' .devcontainer/devcontainer.json .devcontainer.json 2>/dev/null   # DE5: empty config = ⚠️
```

### Setup Scripts
```bash
# Common setup scripts
ls -la setup.sh bootstrap.sh init.sh scripts/setup.sh scripts/bootstrap.sh 2>/dev/null
# DE4 stages the script actually chains (content, never executed)
grep -nE 'install|migrat|seed' setup.sh bootstrap.sh init.sh scripts/setup.sh scripts/bootstrap.sh 2>/dev/null | head -10

# Makefile setup targets
grep -E "^(setup|install|bootstrap|init):" Makefile 2>/dev/null

# package.json setup scripts
grep -E '"(setup|postinstall|prepare)"' package.json 2>/dev/null
```

### Runtime Version
```bash
# System dependencies documented? (mise is asdf's dominant 2025+ successor; corepack via packageManager)
ls -la .tool-versions .node-version .nvmrc .python-version .ruby-version .mise.toml mise.toml 2>/dev/null
grep -E '"packageManager"' package.json 2>/dev/null   # corepack-pinned pm+version
```

### Documentation
```bash
# Setup documentation
ls -la INSTALL.md SETUP.md docs/setup.md docs/getting-started.md 2>/dev/null

# Check README for setup section
grep -i "## setup\|## installation\|## getting started\|## prerequisites" README.md 2>/dev/null
```

## Output Format

Key every finding to the Pillar 5 criterion IDs in prime's `pillars.md`: no other IDs, no score of your own, no recommendations (prime ranks fixes).

```markdown
## Environment Scout Findings

| ID | Criterion | Status | Evidence |
|----|-----------|--------|----------|
| DE1 | .env.example mirrors real env reads | ✅/⚠️/❌ | [template path; declared vs read counts; undeclared vars quoted] |
| DE2 | .env gitignored | ✅/❌ | [.gitignore line; any committed .env path] |
| DE3 | Runtime version pinned | ✅/❌ | [pin file or packageManager line] |
| DE4 | Setup script chains real stages | ✅/⚠️/❌ | [script path + install/migrate/seed lines found] |
| DE5 | Devcontainer is non-empty | ✅/⚠️/❌/N/A | [features / postCreateCommand quoted] |
| DE6 | Docker available | ✅/❌/N/A | [Dockerfile / compose file] |

Notes (unscored context, e.g. setup docs location): [...]
```

## Rules

- Speed over completeness - file existence checks first
- Compare env vars in code vs template (flag gaps)
- Don't read full Dockerfiles - just confirm existence
- Note if setup requires manual steps not documented
- Flag a committed `.env` file (real secret-leak risk) — check it, don't just assert it:
  `git ls-files | grep -E '^(.*/)?\.env(\.[^.]+)?$' | grep -v '\.example$\|\.sample$\|\.template$'`
  (deep secret scanning is security-scout's job; this is the one env-specific leak)
- **Missing vs. failed:** if NONE of `.git`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile` exist at the scan root, emit `SCAN INCONCLUSIVE — no repo markers` instead of a wall of ❌ (an all-❌ from scanning the wrong dir must not read as a bare repo).

© Gordon Mickel · MIT · gmickel/flow-next

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
tooling-scout tooling-scout scans projects for linters, formatters, type checkers and hooks. It is invoked by /flow-next:prime and should not be called directly. CX Codex ★ 730repo stars flow-next-resolve-pr flow-next-resolve-pr coordinates resolution of GitHub PR review feedback, dispatches resolver agents across threads, and closes discussions via GraphQL. CX Codex +1 ★ 730repo stars build-scout build-scout scans project build setup, run commands, CI, and output files. It works through /flow-next:prime, not as a standalone command. CX Codex ★ 730repo stars flow-next-qa flow-next-qa drives a running app through scenarios pulled from the spec and logs P0/P1/P2 findings backed by captured evidence. Finishes with a ship verdict, yes or no. CX Codex +1 ★ 730repo stars testing-scout The testing-scout subagent inspects a project’s test setup, coverage configuration, and CI. It runs through /flow-next:prime, not as a direct invocation. CX Codex ★ 730repo stars why-scout why-scout — a subagent that searches git, PRs, and memory to find why code is structured a certain way. Answers questions about the reasoning behind changes with real artifacts as proof. CX Codex ★ 730repo stars docs-scout docs-scout finds version-matched documentation and inline API signatures for a feature. Helps prep technical context before coding. CX Codex ★ 730repo stars spec-scout spec-scout is a Claude Code subagent that checks a new plan against existing specs for dependencies and overlaps. Run it before planning changes to shared files or APIs. CX Codex ★ 730repo stars

Project sponsors

Companies that keep this analytics open