Analyze Project

Scan a project and produce or update docs/TechStack.md and docs/ProjectStructure.md — living documentation that any AI agent session can read to instantly understand the project without re-scanning from scratch.

When to Use

• Starting work on a project for the first time
• Before any feature work when project docs don't exist yet
• Periodically to keep docs current after codebase changes
• After major refactors, dependency upgrades, or service additions

When NOT to use: docs/TechStack.md and docs/ProjectStructure.md exist and no significant structural changes (config files, directories, container configs) have occurred since the last scan.

Input

• A project or workspace root (provided by user or detected from workspace)

Output

• docs/TechStack.md — concise tech stack reference card
• docs/ProjectStructure.md — operational project map
• In monorepos: per-service copies under [service-path]/docs/

The Process

Step 1: Check Existing Docs

Check if docs/TechStack.md and docs/ProjectStructure.md exist at the project root.

If they exist, read them and extract the YAML frontmatter:

---
generated-by: analyze-project
date: 2024-03-14T12:00:00Z
commit: abc1234
---

If the files exist, hold their contents — you'll compare against fresh scan results later.

Step 2: Staleness Gate

Run git rev-parse --short HEAD to get the current commit hash.

If the commit field in frontmatter differs from HEAD (it usually will — it records the commit at last scan, not the latest), check what actually changed:

Run git diff --name-only <frontmatter-commit>..HEAD to get committed changes, and git status --short to get uncommitted changes (staged, unstaged, and untracked files). Combine both lists.

Evaluate whether the changes are significant for project docs:

• Significant changes (trigger re-scan): new/removed/renamed config files (package.json, composer.json, docker-compose.yml, Dockerfile, Makefile, *.config.*, etc.), new/removed top-level directories, changes to .devcontainer/, CI config changes, README/INSTALL/SETUP changes
• Insignificant changes (skip re-scan): source code changes within existing directories, test changes, asset changes, documentation changes in subdirectories

Decision:

• Files don't exist → Proceed to scan.
• Files exist, commits match HEAD → Report "Project docs are up to date." and stop.
• Files exist, commits differ, only insignificant changes → Report "Project docs are up to date (no structural changes since last scan)." and stop.
• Files exist, commits differ, significant changes detected → Report which files changed and proceed to scan.
• No commit field in frontmatter → Proceed to scan.

If git is not available, skip this check and always proceed to scan.

Step 3: Ownership Check

For each existing file, check the generated-by field in YAML frontmatter:

• generated-by: analyze-project present → Skill owns this file. Will update without asking.
• File exists but no generated-by: analyze-project → Manually authored. Ask the user before overwriting:

"docs/TechStack.md exists but wasn't generated by this skill. Overwrite it? (yes/no)"

If user declines, skip that file and report findings in chat instead.

Step 4: Scan Root

List the project root directory. Read relevant files found:

Config files (reveal tech stack):

• package.json, composer.json, Cargo.toml, go.mod, pyproject.toml, Gemfile, build.gradle, pom.xml, etc.
• tsconfig.json, vite.config.*, webpack.config.*, nuxt.config.*, etc.

Container and dev environment:

• docker-compose.yml / docker-compose.yaml
• Dockerfile
• .devcontainer/devcontainer.json

CI/CD:

• .github/workflows/*.yml
• .gitlab-ci.yml
• Jenkinsfile

Documentation:

• README.md
• INSTALL.md, SETUP.md

Quality tooling:

• Makefile
• .eslintrc.*, eslint.config.*
• .prettierrc
• phpunit.xml, vitest.config.*, jest.config.*, pytest.ini

Start from the root listing. If root has enough config files, that's all you need. If root contains only a single folder (e.g., the repo wraps one project in a subdirectory), treat that folder as the effective root and list it instead. If root is unclear, run a quick glob for config files (**/{*.yml,*.yaml,*.json,*.toml,*.ini,*.md}) limited to a small number of results — the paths reveal where projects and services live (e.g., services/api/package.json). Then read those directories. Avoid full recursive filesystem scans.

Step 5: Detect Monorepo

Check for monorepo signals from what was found in Step 4:

• Directories named apps/, services/, packages/ at root
• docker-compose.yml defining multiple services with build contexts
• Workspace config in package.json (workspaces field) or pnpm-workspace.yaml
• Multiple Dockerfile references in different subdirectories

If monorepo detected, identify service directories and their names.

Step 6: Scan Services (monorepo only)

For each service directory identified in Step 5, apply the same root-reading approach:

1. List the service directory
2. Read its config files (package.json, composer.json, Dockerfile, etc.)
3. Read its README.md if present
4. Note its doc location, dev/lint/test commands

Step 7: Write Docs

Use the templates from references/formats.md.

Single project:

• Write docs/TechStack.md with tech stack reference card
• Write docs/ProjectStructure.md with operational project map
• ProjectStructure.md ends with a "See Also" link to DatabaseStructure.md

Monorepo:

• Write root docs/TechStack.md with shared stack + per-service summary
• Write root docs/ProjectStructure.md with service table and monorepo-level overview
• For each service, write [service-path]/docs/TechStack.md and [service-path]/docs/ProjectStructure.md
• Create docs/ directories if they don't exist

All files get YAML frontmatter with:

• generated-by: analyze-project
• date: current ISO 8601 datetime
• commit: current short git commit hash

Announce the saved paths:

"Project docs updated:

• docs/TechStack.md
• docs/ProjectStructure.md [per-service paths if monorepo] Commit: [hash]"

Common Rationalizations

Rationalization	Reality
"The README has all this info"	READMEs describe intent and setup steps. TechStack and ProjectStructure describe current reality in a structured, machine-readable format.
"I can just read package.json"	One config file gives you one piece. These docs synthesize all signals into two quick-read files.
"The project is small, I don't need docs"	Small projects still have a stack, structure, and tooling. Two short files save every future session from re-discovering them.
"Docs will get outdated"	The staleness gate and commit tracking exist specifically to prevent this. Run the skill again.

Red Flags

• Skipping the staleness check and always rewriting (wastes time, loses manual edits)
• Deep-scanning the filesystem instead of reading root
• Not including YAML frontmatter in output files
• Overwriting manually-authored files without asking
• Missing the monorepo detection step on a multi-service project
• Writing rationale or opinions instead of facts in TechStack.md
• Not creating docs/ directory before writing

Verification

Before finishing, confirm:

• Staleness check performed (or git unavailable noted)
• Ownership check performed for existing files
• Root directory listing read (not deep-scanned)
• Relevant config files read
• docs/TechStack.md written with frontmatter and concise stack listing
• docs/ProjectStructure.md written with frontmatter and operational map
• ProjectStructure.md ends with reference to DatabaseStructure.md
• If monorepo: services detected and per-service docs written
• All generated files have generated-by, date, and commit in frontmatter
• Saved paths announced to user