@maggit/claude-workspace 0.1.1

package/assets/skills/changelog/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: changelog
+description: "Generate a changelog from git history. Use when the user says /changelog, asks to generate a changelog, wants a summary of changes between tags/commits/branches, or needs a CHANGELOG.md file created or updated. Triggers: changelog, changes since, release notes from git, what changed."
+---
+
+# Changelog Generator
+
+Generate a well-structured changelog from git history.
+
+## Workflow
+
+1. Detect the repository root via `git rev-parse --show-toplevel`.
+2. Determine the range:
+   - If the user specifies two refs (tags, branches, SHAs), use that range.
+   - Otherwise, find the latest tag with `git describe --tags --abbrev=0` and use `<latest-tag>..HEAD`.
+   - If no tags exist, use the full history.
+3. Collect commits with `git log --pretty=format:"%H|%s|%an|%ad" --date=short <range>`.
+4. Categorize each commit by its conventional-commit prefix or keywords:
+   - **Added** — `feat`, `add`
+   - **Fixed** — `fix`, `bugfix`, `patch`
+   - **Changed** — `refactor`, `update`, `change`
+   - **Deprecated** — `deprecate`
+   - **Removed** — `remove`, `delete`
+   - **Security** — `security`, `vuln`
+   - **Performance** — `perf`
+   - **Documentation** — `docs`
+   - **Other** — anything that doesn't match
+5. Format output following [Keep a Changelog](https://keepachangelog.com/) conventions.
+6. If a `CHANGELOG.md` already exists, prepend the new section below the title. Otherwise create a new file.
+
+## Output Format
+
+```markdown
+# Changelog
+
+## [<version-or-range>] - YYYY-MM-DD
+
+### Added
+- Description of feature (SHA short)
+
+### Fixed
+- Description of fix (SHA short)
+
+...
+```
+
+## Guidelines
+
+- Use imperative mood in descriptions ("Add feature" not "Added feature").
+- Include short SHA (7 chars) for traceability.
+- Group by category, then sort chronologically within each group.
+- Omit empty categories.
+- If the user requests a specific format (e.g., plain text, JSON), adapt accordingly.
+- For monorepos, offer to scope by directory path using `git log -- <path>`.

package/assets/skills/commit/SKILL.md

@@ -0,0 +1,18 @@
+---
+  name: commit
+  description: Generate a commit message and commit staged changes
+  disable-model-invocation: true
+  allowed-tools: Bash, Read
+  ---
+
+  # Commit Changes
+
+  1. Run `git diff --cached` to see what's staged
+  2. If nothing is staged, run `git status` and tell the user
+  3. Generate a commit message using conventional commits format:
+     - `<type>(<scope>): <subject>`
+     - Types: feat, fix, docs, refactor, test, chore
+     - Lowercase, imperative mood, no period
+  4. Run `git commit -m "<message>"`
+
+  If the user provided arguments ($ARGUMENTS), use them as guidance for the message.

package/assets/skills/completetodo/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: completetodo
+description: "Mark TODO items as completed based on work done in the current session. Use when the user says /completetodo, asks to mark todos as done, check off tasks, complete tasks, or update todo progress. Triggers: completetodo, complete todo, mark done, check off, tasks done, finished tasks, update todos."
+---
+
+# Complete TODO
+
+Review the current conversation, identify work that has been completed, and mark the corresponding TODO items as done in `ContextDB/todos/`.
+
+## Workflow
+
+1. **Scan for active TODO files:**
+   - List all files in `ContextDB/todos/`.
+   - **Skip** files prefixed with `completed-` (these are fully done).
+   - Read each remaining file and collect all open items (`- [ ]`).
+
+2. **Match completed work against open TODOs:**
+   - Review the current conversation to understand what was accomplished.
+   - For each open TODO item, determine if the work described has been done in this session.
+   - Be thorough but conservative — only mark items as done if you're confident the work is complete, not just started.
+
+3. **If the user provides specific items to complete:**
+   - The user may say things like "mark the auth task as done" or list specific items.
+   - Match their description to the closest open TODO item(s).
+   - If ambiguous, show the matching candidates and ask which one(s) to mark.
+
+4. **Update the file(s):**
+   - Replace `- [ ]` with `- [x]` for each completed item.
+   - Add a completion timestamp as an inline comment:
+     ```markdown
+     - [x] Implement login endpoint in `app/api/auth/route.ts` <!-- completed 2026-02-07 14:30 -->
+     ```
+   - **Do not** modify any other content in the file.
+   - **Do not** remove items — completed items stay in the file as a record.
+
+5. **Check if the entire file is now complete:**
+   - After updating, count remaining `- [ ]` items in the file.
+   - If **zero open items remain**, rename the file:
+     - From: `2026-02-07-auth-refactor-todo.md`
+     - To: `completed-2026-02-07-auth-refactor-todo.md`
+   - This signals to `/opentodos` that the file can be skipped entirely.
+
+6. **Report to the user:**
+   - List which items were marked as done.
+   - List any items that are still open.
+   - If a file was renamed to `completed-`, mention that.
+
+## Example
+
+**Before:**
+```markdown
+- [ ] Add login endpoint
+- [ ] Create JWT utility
+- [x] Set up auth middleware <!-- completed 2026-02-06 10:15 -->
+```
+
+**After running `/completetodo` (login endpoint was built this session):**
+```markdown
+- [x] Add login endpoint <!-- completed 2026-02-07 14:30 -->
+- [ ] Create JWT utility
+- [x] Set up auth middleware <!-- completed 2026-02-06 10:15 -->
+```
+
+## Guidelines
+
+- Read the actual conversation — don't guess. Only mark items you have evidence were completed.
+- If a task was partially done, do NOT mark it as complete. Instead, leave it open and optionally add a sub-note:
+  ```markdown
+  - [ ] Implement user authentication
+    - [x] Login endpoint done <!-- completed 2026-02-07 -->
+    - [ ] Token refresh still pending
+  ```
+- Preserve the original wording of TODO items — don't rewrite them.
+- If no TODOs match the current session's work, say so honestly.
+- Always confirm what you're about to mark before writing, especially if the match is fuzzy.

package/assets/skills/createtodo/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: createtodo
+description: "Create a TODO list in ContextDB/todos/. Use when the user says /createtodo, asks to create a todo, add tasks, make a task list, or track work items. Triggers: createtodo, create todo, add todo, new todo, task list, things to do, track tasks, add tasks."
+---
+
+# Create TODO
+
+Create or append to a TODO list stored as a Markdown file in `ContextDB/todos/`.
+
+## Workflow
+
+1. **Determine the TODOs to add:**
+   - If the user provides explicit items → use those exactly as stated.
+   - If the user says something vague like "create a todo for what's pending" → review the current conversation and extract actionable items that are unfinished, discussed, or planned.
+   - Ask for clarification only if you truly can't determine what should go on the list.
+
+2. **Check for an existing active TODO file for today:**
+   - Look in `ContextDB/todos/` for a file matching today's date pattern: `YYYY-MM-DD-*-todo.md` (excluding files prefixed with `completed-`).
+   - If one exists for today → **append** new items to it rather than creating a duplicate file.
+   - If none exists → create a new file.
+
+3. **Create or update the file:**
+   - **Directory:** `ContextDB/todos/`
+   - **Filename format:** `YYYY-MM-DD-<topic>-todo.md`
+     - `<topic>` is a short kebab-case label derived from the user's request or the main theme.
+     - If no clear topic, use `general`: `2026-02-07-general-todo.md`
+     - Examples: `2026-02-07-auth-refactor-todo.md`, `2026-02-07-general-todo.md`
+   - Get the current date via `date "+%Y-%m-%d"` in bash.
+
+4. **File format:**
+
+```markdown
+# TODO — <Topic> — YYYY-MM-DD
+
+## Tasks
+
+- [ ] Task description
+- [ ] Task description with details
+- [ ] Task description
+
+## Notes
+
+<Optional section for any context, links, or background that helps understand the tasks.>
+```
+
+### Rules for TODO items:
+- Each item uses a Markdown checkbox: `- [ ]` (open) or `- [x]` (completed).
+- Items should be **actionable and specific** — not vague ("fix stuff") but clear ("Fix the auth redirect bug in `lib/auth.ts`").
+- Include file paths, function names, or specific details when relevant.
+- You may add sub-items with indentation for complex tasks:
+  ```
+  - [ ] Implement user authentication
+    - [ ] Add login endpoint in `app/api/auth/route.ts`
+    - [ ] Create JWT token utility in `lib/jwt.ts`
+    - [ ] Add auth middleware in `middleware.ts`
+  ```
+- You may add priority with a prefix: `[P0]`, `[P1]`, `[P2]` (where P0 = critical, P1 = important, P2 = nice to have).
+- You may add categories with a prefix in **bold**: `**frontend**`, `**backend**`, `**infra**`, etc.
+
+5. **When appending to an existing file:**
+   - Read the current file first.
+   - Add new items **below the existing items** in the `## Tasks` section.
+   - Add a separator comment so it's clear when items were added:
+     ```
+     <!-- Added YYYY-MM-DD HH:MM -->
+     - [ ] New task
+     ```
+
+6. **Confirm to the user:**
+   - Show the filename.
+   - List the items that were added.
+
+## Guidelines
+
+- Never overwrite existing TODO items — only append.
+- If the user asks to "update" a todo, read it first and ask what to change.
+- Keep descriptions concise but unambiguous.
+- This skill only **creates/appends** items. Use `/completetodo` to mark items done.
+- Use `/opentodos` to review pending items.

package/assets/skills/deadcode/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: deadcode
+description: "Find and remove dead, unused, or unreachable code in a codebase. Use when the user says /deadcode, asks to find unused code, dead code, unreachable code, orphaned files, unused imports, unused variables, or wants to clean up a codebase. Triggers: dead code, unused, unreachable, orphan, cleanup, prune."
+---
+
+# Dead Code Detector
+
+Find and safely remove dead, unused, or unreachable code.
+
+## Workflow
+
+1. Determine scope:
+   - Specific file/directory or entire project.
+   - Specific language(s) to focus on.
+2. Identify the project type and entry points:
+   - Check for `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.
+   - Identify entry points (main files, exported modules, route handlers).
+3. Scan for dead code by category:
+
+### Categories to Check
+
+**Unused Imports/Requires**
+- Scan each file for imported symbols not referenced in the file body.
+
+**Unused Exports**
+- Find exported functions/classes/constants and search the codebase for their usage.
+- Use `grep -r` or equivalent to verify each export is imported elsewhere.
+
+**Unused Variables & Parameters**
+- Identify declared variables never read.
+- Find function parameters never referenced in the function body.
+- Respect `_` prefix convention for intentionally unused params.
+
+**Unreachable Code**
+- Code after unconditional `return`, `throw`, `break`, `continue`.
+- Conditions that are always true/false (e.g., `if (false)`).
+
+**Unused Files**
+- Files not imported/required by any other file.
+- Test files and config files should be excluded from this check.
+
+**Commented-Out Code**
+- Large blocks of commented code (>5 lines) that are likely stale.
+
+4. Present findings grouped by category with file paths and line numbers.
+5. For each finding, assess confidence (high/medium/low) based on static analysis limitations.
+6. Remove only with user approval, starting with high-confidence items.
+
+## Guidelines
+
+- Never auto-delete — always present findings and ask for confirmation.
+- Respect dynamic usage patterns: `getattr()`, `eval()`, reflection, decorators, dependency injection.
+- Check for framework conventions (e.g., Django views referenced in urls.py, React components used in JSX).
+- Exclude test files, config files, and type definition files from "unused" reports.
+- For libraries/packages, exported public API should not be flagged as dead code.
+- Note limitations: static analysis cannot catch all dynamic references.

package/assets/skills/debug/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: debug
+description: "Systematically debug issues in code. Use when the user says /debug, reports a bug, error, unexpected behavior, crash, exception, or needs help troubleshooting. Triggers: debug, bug, error, traceback, exception, crash, not working, broken, unexpected behavior, troubleshoot, investigate."
+---
+
+# Debug Assistant
+
+Systematically diagnose and fix bugs.
+
+## Workflow
+
+1. **Gather context:**
+   - Ask for or locate the error message, traceback, or unexpected behavior description.
+   - Identify the file(s) and function(s) involved.
+   - Check recent git changes: `git log --oneline -10` and `git diff HEAD~3`.
+
+2. **Reproduce:**
+   - Understand the reproduction steps.
+   - If a test exists, run it to confirm the failure.
+   - If no test exists, suggest a minimal reproduction.
+
+3. **Hypothesize:**
+   - Form 2-3 hypotheses based on the error type.
+   - Rank by likelihood.
+
+4. **Investigate top hypothesis:**
+   - Read the relevant code carefully.
+   - Trace the data flow from input to error.
+   - Check edge cases: null/undefined, empty collections, type mismatches, off-by-one, race conditions.
+   - Look at recent changes to the affected code with `git log -p -- <file>`.
+
+5. **Identify root cause:**
+   - Distinguish symptom from cause.
+   - Check if the bug exists in other similar code paths.
+
+6. **Fix:**
+   - Propose the minimal change that fixes the root cause.
+   - Explain why the fix works.
+   - Check for related bugs in similar patterns.
+
+7. **Verify:**
+   - Run existing tests.
+   - Suggest a new test that would have caught this bug.
+
+## Common Bug Patterns
+
+| Pattern | What to check |
+|---------|--------------|
+| TypeError/AttributeError | Null checks, type coercion, missing fields |
+| Off-by-one | Loop bounds, array indexing, fence-post |
+| Race condition | Shared state, async/await, locks |
+| State mutation | Unexpected side effects, shallow copies |
+| Import/dependency | Version mismatches, circular imports |
+| Environment | Missing env vars, wrong paths, permissions |
+
+## Guidelines
+
+- Read the actual error message carefully — it usually points to the answer.
+- Check the simplest explanation first.
+- Don't change code you don't understand. Read it first.
+- One fix at a time. Verify before moving on.
+- If the fix is a workaround, document it and note the underlying issue.

package/assets/skills/deps/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: deps
+description: "Analyze, audit, and manage project dependencies. Use when the user says /deps, asks to check dependencies, find outdated packages, audit for vulnerabilities, analyze dependency trees, or clean up unused packages. Triggers: deps, dependencies, outdated, audit, vulnerabilities, upgrade packages, dependency tree, unused packages, npm audit, pip audit."
+---
+
+# Dependency Manager
+
+Analyze, audit, and manage project dependencies.
+
+## Workflow
+
+1. **Detect the package ecosystem:**
+   - `package.json` → npm/yarn/pnpm
+   - `pyproject.toml` / `requirements.txt` → pip/poetry/uv
+   - `Cargo.toml` → cargo
+   - `go.mod` → Go modules
+   - `Gemfile` → bundler
+   - `pom.xml` / `build.gradle` → Maven/Gradle
+
+2. **Run the requested analysis:**
+
+### Outdated Dependencies
+- `npm outdated` / `yarn outdated` / `pnpm outdated`
+- `pip list --outdated`
+- `cargo outdated` (if installed)
+- `go list -u -m all`
+- Present as a table: package, current, wanted, latest, type (major/minor/patch).
+
+### Security Audit
+- `npm audit` / `yarn audit` / `pnpm audit`
+- `pip audit` / `safety check`
+- `cargo audit`
+- `govulncheck ./...`
+- Categorize findings by severity (critical, high, medium, low).
+- For each vulnerability, show: package, severity, description, fix available.
+
+### Unused Dependencies
+- Cross-reference declared dependencies against actual imports in the codebase.
+- Check `devDependencies` vs runtime usage.
+- Flag dependencies that are declared but never imported.
+
+### Dependency Tree Analysis
+- `npm ls --all` / `yarn why <pkg>` / `pnpm why <pkg>`
+- `pipdeptree`
+- Identify duplicate packages at different versions.
+- Find heavy transitive dependencies.
+
+### Upgrade Plan
+For major upgrades, generate a plan:
+```
+1. Upgrade <package> from v2.x to v3.x
+   - Breaking changes: <list from changelog>
+   - Required code changes: <files affected>
+   - Risk: <low/medium/high>
+```
+
+3. **Present findings with actionable recommendations.**
+
+## Guidelines
+
+- Always show the impact before suggesting upgrades (breaking changes, migration effort).
+- For security vulnerabilities, prioritize by exploitability and exposure, not just CVSS score.
+- Suggest pinning strategies: exact versions for apps, ranges for libraries.
+- Warn about packages that are unmaintained (no commits in >1 year, deprecated).
+- Don't auto-upgrade — always present the plan and get user confirmation.
+- Check license compatibility if the user asks or if the project has a LICENSE file.

package/assets/skills/e2e/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: e2e
+description: "Generate end-to-end tests for applications. Use when the user says /e2e, asks for end-to-end tests, integration tests, browser tests, API tests, or wants to test a full user workflow. Triggers: e2e, end-to-end, integration test, browser test, playwright, cypress, selenium, API test, smoke test, user flow."
+---
+
+# E2E Test Generator
+
+Generate end-to-end tests covering full user workflows.
+
+## Workflow
+
+1. **Detect the E2E framework:**
+   - Check for existing config: `playwright.config.*`, `cypress.config.*`, `wdio.conf.*`.
+   - Check `package.json` for Playwright, Cypress, Selenium, Puppeteer, or similar.
+   - For API-only: check for Supertest, httpx, REST-assured.
+   - If none exists, recommend Playwright (most versatile) and help set it up.
+
+2. **Identify the user flow to test:**
+   - Ask the user or infer from the feature being discussed.
+   - Map out the steps: navigation, input, actions, expected outcomes.
+   - Identify preconditions (auth state, seed data, feature flags).
+
+3. **Generate the test:**
+
+### For Browser E2E (Playwright/Cypress)
+
+```
+- Navigate to the page.
+- Interact with elements using accessible selectors (role, label, text).
+- Assert on visible outcomes (text content, URL, element state).
+- Handle async loading (wait for network idle, element visibility).
+```
+
+### For API E2E
+
+```
+- Set up auth headers/tokens.
+- Make requests in the order a real client would.
+- Assert on status codes, response bodies, and side effects.
+- Clean up test data.
+```
+
+4. **Add robustness:**
+   - Use data-testid or accessible selectors, not brittle CSS selectors.
+   - Add proper waits instead of fixed timeouts.
+   - Handle flakiness: retry logic, deterministic test data.
+   - Set up and tear down test state.
+
+5. **Run the test** to verify it passes.
+
+## Test Structure
+
+```
+describe('User flow: <flow name>')
+  before: Set up preconditions (login, seed data)
+  test: Step-by-step user actions with assertions
+  after: Clean up (delete test data, logout)
+```
+
+## Guidelines
+
+- E2E tests should mirror real user behavior — interact via the UI, not internal APIs.
+- Keep E2E tests focused on critical paths (login, checkout, core CRUD).
+- Use accessible selectors: `getByRole`, `getByLabel`, `getByText` over CSS.
+- Isolate test data — don't depend on shared mutable state.
+- E2E tests are slow; keep the suite lean. Test edge cases in unit tests.
+- For flaky tests, add retry annotations rather than arbitrary sleeps.
+- Include visual regression snapshots for UI-critical flows if the framework supports it.

package/assets/skills/eng-spec/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: eng-spec
+description: "Generate an Engineering Specification. Use when the user says /eng-spec, asks to create a technical spec, engineering spec, system design document, or translate a PRD into a technical plan. Triggers: eng-spec, engineering spec, technical spec, system design, technical design, architecture spec."
+---
+
+# Engineering Specification
+
+## Purpose
+
+Generate a detailed engineering specification that translates product requirements into a concrete technical plan. The spec gives engineers a clear blueprint for implementation, covering architecture, data models, APIs, and operational concerns.
+
+## When to Use
+
+- After a PRD has been approved and engineering work is about to begin
+- When a technical approach needs to be documented for review
+- When onboarding engineers to an existing system's design
+
+## Inputs
+
+- **Feature or system name**: What is being specified
+- **Product requirements or PRD**: The "what" that this spec addresses
+- **Technical context**: Existing stack, services, constraints (optional but helpful)
+- **Scale expectations**: Expected load, data volume, user count (optional)
+
+## Output Format
+
+Produce a markdown document with the following sections:
+
+### 1. System Overview
+A brief description of what the system or feature does and how it fits into the broader architecture. Include a high-level diagram description if helpful.
+
+### 2. Architecture Decisions
+List key technical decisions using the format:
+- **Decision**: What was decided
+- **Rationale**: Why this approach was chosen
+- **Alternatives considered**: What else was evaluated and why it was rejected
+
+### 3. Data Models
+Define the core entities, their fields, types, and relationships. Use table format:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+
+Include notes on indexing, constraints, and migration from existing schemas.
+
+### 4. API Contracts
+For each endpoint or interface, specify:
+- Method and path (or function signature)
+- Request parameters and body schema
+- Response schema with status codes
+- Authentication and authorization requirements
+- Rate limiting or usage constraints
+
+### 5. Error Handling
+Define the error strategy:
+- Error categories and codes
+- Retry behavior and idempotency
+- User-facing vs. internal error messages
+- Logging and alerting requirements
+
+### 6. Testing Strategy
+Outline the testing approach:
+- **Unit tests**: Key logic to cover
+- **Integration tests**: Service boundaries to validate
+- **End-to-end tests**: Critical user flows
+- **Performance tests**: Load and latency benchmarks
+
+### 7. Migration Plan
+If this changes existing systems:
+- Step-by-step migration sequence
+- Data backfill requirements
+- Feature flag strategy
+- Rollback procedure
+
+### 8. Security Considerations
+Address authentication, authorization, data encryption, input validation, and any compliance requirements.
+
+### 9. Open Questions and Risks
+List unresolved technical questions and identified risks with proposed mitigations.
+
+## Example
+
+**Input**: "We need an eng spec for the PDF export feature described in the PRD. Our stack is Node.js, PostgreSQL, and AWS."
+
+**Output**: A full engineering spec covering the architecture (async job queue with S3 storage for generated PDFs), data models (ExportJob, ExportTemplate tables), API contracts (POST /exports to trigger, GET /exports/:id to poll status, GET /exports/:id/download for retrieval), error handling (retry failed renders up to 3 times, notify user on permanent failure), testing strategy (unit tests for template rendering, integration tests for the job pipeline, load tests for concurrent generation), and migration plan (new tables, no schema changes to existing).
+
+## Guidelines
+
+- Be precise about data types, constraints, and expected values
+- Separate the "happy path" from edge cases and error flows
+- Include enough detail for an engineer to implement without ambiguity
+- Call out dependencies on other teams or services explicitly
+- Keep security and observability as first-class concerns, not afterthoughts

package/assets/skills/envcheck/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: envcheck
+description: "Check environment setup, dependencies, and configuration for issues. Use when the user says /envcheck, asks to verify their environment, diagnose setup issues, check prerequisites, or troubleshoot configuration problems. Triggers: envcheck, environment check, setup check, verify setup, check config, prerequisites, system requirements, doctor, health check."
+---
+
+# Environment Check
+
+Diagnose environment setup, dependencies, and configuration.
+
+## Workflow
+
+1. **Detect the project type** from manifest files and directory structure.
+
+2. **Run checks by category:**
+
+### Runtime & Tools
+- Language version: `node -v`, `python3 --version`, `go version`, `rustc --version`, `java -version`.
+- Package manager: `npm -v`, `yarn -v`, `pnpm -v`, `pip --version`, `cargo --version`.
+- Required CLI tools: `git`, `docker`, `gh`, framework CLIs.
+- Compare against version requirements in `.nvmrc`, `.python-version`, `.tool-versions`, `engines` field, etc.
+
+### Dependencies
+- Are dependencies installed? Check for `node_modules/`, `venv/`, `vendor/`.
+- Are lockfiles up to date? Compare `package.json` vs `package-lock.json` timestamps.
+- Any missing native dependencies? (e.g., `sharp`, `bcrypt`, `psycopg2`).
+
+### Configuration
+- Required environment variables: scan `.env.example`, `.env.template`, or code for `process.env.*`, `os.environ.*`.
+- Compare against actual `.env` file — report missing variables.
+- Config file validity: JSON/YAML syntax, required fields.
+
+### Services
+- Database connectivity: check if expected port is open (`pg`, `mysql`, `redis`, `mongo`).
+- Docker: `docker compose ps` if `docker-compose.yml` exists.
+- Required services running.
+
+### Permissions & Paths
+- File permissions on scripts, SSH keys.
+- PATH includes required directories.
+- Write permissions on output directories.
+
+3. **Present results as a checklist:**
+
+```
+Environment Check Results
+=========================
+[PASS] Node.js v20.11.0 (required: >=18)
+[PASS] npm v10.2.0
+[PASS] Dependencies installed (node_modules exists)
+[WARN] Lockfile is 3 days older than package.json — consider running npm install
+[FAIL] Missing env var: DATABASE_URL (required by src/db.ts)
+[FAIL] PostgreSQL not reachable on localhost:5432
+[PASS] Docker running
+[PASS] Git configured (user.name and user.email set)
+
+3 passed, 1 warning, 2 failures
+```
+
+## Guidelines
+
+- Use color-coded symbols: PASS, WARN, FAIL.
+- For each failure, include the fix command or action needed.
+- Run non-destructive checks only — never modify the environment.
+- Check project-specific requirements first (from docs or config), then general tooling.
+- If a `.env.example` exists, use it as the source of truth for required variables.