name: project-inventory
description: "Take stock of a project before any changes — identify the project, survey files, analyze recency, diff local vs remote, and verify readability. Use as the first phase of a deployment pipeline or when you need to understand a project's current state."

Project Inventory

Establish a baseline: what the project IS, what state it's in, and how it differs from what's deployed. This is always Phase 1 — nothing else runs until you know what you're working with.

Steps

1. Identify the project

Read package.json, Cargo.toml, pyproject.toml, CLAUDE.md, README, or equivalent to determine:

• Project name — used throughout the pipeline and report
• Description / purpose — one sentence
• Tech stack — framework, language, hosting platform
• Git remotes and branches — which remote triggers deployment

2. File tree survey

Collect:

• Total file count by type (source, test, config, assets)
• Total lines of code (adapt to the project's language):
  bash find src -name '*.ts' -o -name '*.tsx' | xargs wc -l
• Directory structure summary (top-level dirs and their purpose)
• Any files that appear stale, empty, or misplaced

3. Recency analysis

Build a file modification histogram — how many source files were modified in the last 24h, 7d, 30d, 90d, and older. This reveals whether the project is actively developed or dormant, and where recent work is concentrated.

• Most recently modified files (top 10):
  bash /bin/ls -lt src/ | /usr/bin/head -10
• For time bucketing, use find ... | xargs stat -f '%m' (macOS) and arithmetic comparison against $(date +%s) minus the interval in seconds
• Avoid strftime (GNU awk only) — see shell-portability.md

4. Local vs remote diff

Compare the working tree to what's on the remote:

git status                                  # uncommitted changes
git log origin/main..HEAD --oneline         # local commits not yet pushed
git log HEAD..origin/main --oneline         # remote commits not yet pulled

Summary format: "N files changed locally, M commits ahead, K commits behind"

5. Verify readability

Spot-check that key files are readable and non-empty:

• Entry point (e.g., src/app/layout.tsx, src/main.ts, main.py)
• Config files (package.json, tsconfig.json, etc.)
• Test directory exists and contains tests
• Flag anything that looks broken (empty files, missing expected directories)

Collect

• Project name, description, stack
• File counts by type and total LOC
• Recency histogram (24h / 7d / 30d / 90d / older)
• Top 10 recently modified files
• Local vs remote diff summary
• Any anomalies (empty files, missing dirs, unreadable files)

Stop Conditions

STOP if: The project is in an unworkable state (missing entry point, no package manifest, corrupted git). Ask the user before proceeding.