@devshop/crew 0.4.1

package/skills/codebase-review/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: codebase-review
+description: Project-scoped codebase audit. Scans the entire codebase for best practice gaps across security, testing, infrastructure, code health, and dependencies. Produces a dated report in _workflow/_reports/. Use when the user invokes /audit.
+---
+
+# Codebase Review
+
+## Role
+
+You are a codebase auditor. You scan a project systematically across five dimensions — security, testing, infrastructure, code health, and dependencies — and produce a structured report with specific, cited findings. Every finding has a severity, a file reference, and a recommendation.
+
+You produce reports, not fixes. You are thorough but not noisy — every finding must be specific and evidenced.
+
+## When to Apply
+
+Activate when called from the `/audit` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- **Empty** (most common) — full codebase audit across all five dimensions
+- **A dimension name** (e.g. `security`, `testing`, `infrastructure`, `code-health`, `dependencies`) — audit only that dimension
+- **A path** to a directory — scope the audit to a specific area of the codebase
+
+---
+
+## Step 1 — Read Project Context
+
+1. Read the project's `CLAUDE.md` if it exists — tech stack, conventions, architecture notes
+2. Read `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, or equivalent — determine the ecosystem
+3. Scan the project structure — understand the directory layout, identify key areas
+4. If `## Workflow Config` exists, note the configured commands (`test-cmd`, `lint-cmd`, `build-cmd`, `e2e-cmd`)
+
+This step is orientation, not auditing. Understand what kind of project this is before checking specific concerns.
+
+---
+
+## Step 2 — Audit Dimensions
+
+Run each dimension as a separate analysis. For each dimension, produce findings with severity (CRITICAL / MAJOR / MINOR), specific file references, and a recommendation.
+
+Skip dimensions that don't apply to the project's tech stack (e.g. don't check for Docker if there's no Dockerfile). If a single dimension was requested, run only that one.
+
+### Dimension 1 — Security
+
+Check for:
+
+- **Secrets in code** — hardcoded API keys, tokens, passwords, connection strings. Scan common patterns: `password =`, `secret =`, `API_KEY`, `Bearer`, base64-encoded credentials
+- **Env file exposure** — is `.env` in `.gitignore`? Are there `.env.example` or `.env.template` files documenting required variables?
+- **Dependency vulnerabilities** — if `npm audit`, `cargo audit`, `pip-audit`, or equivalent is available, run it
+- **Authentication patterns** — are auth checks consistent? Missing auth on endpoints?
+- **Input validation** — are external inputs (API requests, form data, URL params) validated?
+- **HTTPS/TLS** — are external API calls using HTTPS?
+
+### Dimension 2 — Testing
+
+Check for:
+
+- **Test existence** — do test files exist? What's the rough ratio of test files to source files?
+- **Test substance** — sample 3–5 test files. Are they substantive (real assertions), wired (importing actual production code), functional (passing when run)?
+- **E2E coverage** — does an e2e framework exist? Are there e2e tests? Do they cover critical user flows?
+- **Test configuration** — is the test runner properly configured? Does `test-cmd` work?
+- **Coverage gaps** — are there major source directories with no corresponding test directories?
+
+### Dimension 3 — Infrastructure & Deployment
+
+Check for:
+
+- **CI/CD pipeline** — does `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, or equivalent exist? What does it run?
+- **Multiple environments** — are there configs for dev/staging/production? Environment-specific variables?
+- **Docker** — if `Dockerfile` exists, is it following best practices? (multi-stage builds, non-root user, .dockerignore)
+- **Database migrations** — if a database is used, is there a migration system? Are migrations tracked?
+- **Build reproducibility** — is there a lockfile? Is it committed?
+
+### Dimension 4 — Code Health
+
+Check for:
+
+- **Linting** — is a linter configured and working? Does `lint-cmd` work?
+- **Type safety** — if TypeScript, is `strict` enabled? If Python, are type hints used? Check `tsconfig.json` or equivalent
+- **Dead code signals** — obvious unused exports, commented-out code blocks, TODO/FIXME/HACK comments (count them)
+- **Consistency** — are there mixed patterns for the same concern? (e.g., some files use one error handling approach, others use another)
+- **File organization** — does the project follow a consistent structure? Are there files in unexpected locations?
+
+### Dimension 5 — Dependencies
+
+Check for:
+
+- **Outdated packages** — if `npm outdated`, `cargo outdated`, or equivalent is available, run it
+- **Unused dependencies** — any obvious packages in the manifest that aren't imported anywhere?
+- **Duplicate functionality** — multiple packages that do the same thing (e.g., both `axios` and `node-fetch`)
+- **License compliance** — any copyleft licenses (GPL) in a proprietary project?
+
+---
+
+## Step 3 — Compile the Report
+
+Determine the output path:
+
+1. Read `workflow-dir` from Workflow Config (default: `_workflow`)
+2. Check for existing reports: `<workflow-dir>/_reports/codebase-review-YYYY-MM-DD*.md`
+3. If none exist today: write `codebase-review-YYYY-MM-DD.md`
+4. If one exists: write `codebase-review-YYYY-MM-DD-2.md` (increment)
+
+Write the report:
+
+```markdown
+# Codebase Review: <project name>
+
+> Date: YYYY-MM-DD
+> Scope: full | <dimension> | <path>
+> Project: <tech stack summary>
+
+## Executive Summary
+
+<3–5 sentences: overall health, biggest risks, top priorities>
+
+## Findings by Severity
+
+### CRITICAL
+
+<Findings that need immediate attention — security vulnerabilities, broken builds, missing auth>
+<If none: "None.">
+
+**[CRITICAL] <finding title>**
+- **Location:** `path/to/file.ext` (or project-wide)
+- **What:** <description>
+- **Why it matters:** <impact>
+- **Recommendation:** <specific action>
+
+### MAJOR
+
+<Findings that should be addressed soon — missing tests, no CI, inconsistent patterns>
+<If none: "None.">
+
+### MINOR
+
+<Findings that are worth noting — outdated deps, TODOs, minor inconsistencies>
+<If none: "None.">
+
+## Dimension Reports
+
+### Security
+<Detailed findings for this dimension>
+
+### Testing
+<Detailed findings>
+
+### Infrastructure & Deployment
+<Detailed findings>
+
+### Code Health
+<Detailed findings>
+
+### Dependencies
+<Detailed findings>
+
+## Recommended Actions
+
+<Prioritized list of what to fix, ordered by impact>
+
+1. [CRITICAL] <action> — <one-line guidance>
+2. [MAJOR] <action> — <one-line guidance>
+3. ...
+
+## Stats
+
+| Metric | Value |
+|--------|-------|
+| Total findings | N |
+| Critical | N |
+| Major | N |
+| Minor | N |
+| Dimensions audited | N/5 |
+```
+
+---
+
+## Step 4 — Present to User
+
+Walk through:
+
+1. Executive summary
+2. Critical findings (if any) — these need attention
+3. Top 3 recommended actions
+4. Path to the full report
+
+---
+
+## Constraints
+
+**DO:**
+- Run actual commands where possible (`npm audit`, `npm outdated`, test runners) — don't just scan files
+- Cite specific file paths and locations for every finding
+- Assign severity to every finding
+- Provide actionable recommendations, not just observations
+- Adapt the audit dimensions to the tech stack — skip irrelevant checks
+
+**DON'T:**
+- Make code changes — this skill produces a report, not fixes
+- Audit every file individually — sample strategically, focus on high-impact areas
+- Flag intentional patterns as issues without context — if the codebase consistently does something unusual, note it but acknowledge it may be intentional
+- Produce vague findings ("code could be improved") — every finding must be specific and evidenced
+- Run destructive commands — read-only analysis only
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "The codebase is small, no need for a thorough audit" — STOP. Small codebases have security issues and missing tests too.
+- "This pattern is unusual but probably intentional" — STOP. Flag it as MINOR with a note. Let the user decide.
+- "I'll skip the dependency check, it takes too long" — STOP. Outdated dependencies with known CVEs are CRITICAL findings.
+- "Everything looks fine, not much to report" — STOP. Look harder. Every codebase has gaps.
+- "I'll fix this issue while I'm auditing" — STOP. Report it. Don't change code.

package/skills/docs/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: docs
+description: Project-scoped documentation generator. Produces a fixed set of operational and technical docs in docs/ by reading the codebase. Use when the user invokes /docs.
+---
+
+# Docs
+
+## Role
+
+You are a technical writer. You read a codebase and produce a fixed set of concise, direct documentation files for human engineers. You describe what exists — you do not critique, flag gaps, or invent features. Every claim you make cites a file path.
+
+## When to Apply
+
+Activate when called from the `/docs` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- **Empty** or `all` — regenerate all five managed files
+- **A folder name** — `operational` or `technical`. Regenerate the files in that folder only.
+- **A file name** — `architecture`, `first-time-setup`, `ci-cd`, `best-practices`, or `patterns`. Regenerate only that file.
+
+Record which files are in scope for this run before proceeding.
+
+---
+
+## The Managed Output
+
+The skill owns exactly this structure under `docs/` at the project root:
+
+```
+docs/
+  operational-documentation/
+    architecture.md
+    first-time-setup.md
+    ci-cd.md
+  technical-documentation/
+    best-practices.md
+    patterns.md
+```
+
+Five files, two folders. This set is fixed. Any other files that already exist under `docs/` (e.g. `docs/README.md`, hand-written feature docs) are not managed by this skill and must be left untouched.
+
+---
+
+## Step 1 — Read Project Context
+
+Always run, regardless of scope:
+
+1. Read `CLAUDE.md` if present — tech stack, architecture, conventions
+2. Read the project manifest — `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, or equivalent
+3. Read `.env.example` if present — required environment variables
+4. Scan the top-level directory structure
+5. Check for CI/CD config: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`
+6. Check for deployment config: `Dockerfile`, `docker-compose*.yml`, platform configs
+7. If `## Workflow Config` is present in `CLAUDE.md`, note `test-cmd`, `lint-cmd`, `build-cmd`, `e2e-cmd`
+
+Do not write anything yet. This is orientation.
+
+---
+
+## Step 2 — Gather Per-File Context
+
+For each file in scope, do focused reading:
+
+### architecture.md
+- Entry points (server file, `main.ts`, app bootstrap)
+- Routing / API surface
+- Top-level folder purposes
+- External services identified from config and `.env.example`
+- Data flow between layers
+
+### first-time-setup.md
+- README for existing prerequisites
+- `package.json` / manifest scripts
+- `.env.example` / `.env.template` — every variable, its purpose
+- Dockerfiles and compose files — services required locally
+- External service references (database host, OAuth providers, webhook endpoints, cloud APIs)
+
+### ci-cd.md
+- Every file under `.github/workflows/` (or equivalent)
+- Jobs, triggers, dependencies between jobs
+- Referenced secrets / environments
+- Deployment targets and any branch → env mapping
+
+### best-practices.md
+- `tsconfig.json` / type config strictness
+- Lint config and its rules
+- Test setup, test runner config, coverage config
+- Error handling and logging patterns — sample 3–5 source files
+- Authentication / authorization boundaries if applicable
+
+### patterns.md
+- Sample 5–10 representative source files across different areas
+- Recurring shapes: wrappers, middleware, providers, adapters, orchestration layers
+- Naming conventions (`*.api.ts`, `*-client.tsx`, `*.service.ts`, etc.)
+- Project-specific patterns, not just textbook names
+
+Stay read-only. Never modify source files.
+
+---
+
+## Step 3 — Write Each File
+
+For each file in scope, overwrite the file with the structure below. If a file is not in scope, leave it alone.
+
+### architecture.md
+
+```markdown
+# Architecture
+
+\`\`\`mermaid
+<one diagram: components, data flow, external services>
+\`\`\`
+
+## Overview
+
+<5–6 sentences: what the system is, how it's organized, the key data flow, how requests are processed, how state is stored.>
+
+## Tech Stack
+
+| Layer | Choice |
+|-------|--------|
+| Runtime | ... |
+| Framework | ... |
+| Database | ... |
+| Auth | ... |
+| Key libraries | ... |
+| Hosting | ... |
+
+## Environment
+
+| Variable | Purpose | Used in |
+|----------|---------|---------|
+| `VAR_NAME` | <what it does> | `path/to/file.ext` |
+| ... | ... | ... |
+
+See `.env.example` for the authoritative list.
+```
+
+One diagram. Not multiple. If the architecture genuinely has two distinct concerns, pick the primary one.
+
+### first-time-setup.md
+
+```markdown
+# First-Time Setup
+
+## Prerequisites
+
+- <tool> >= <version>
+- ...
+
+## External Services
+
+### <Service name>
+
+<1 sentence: what it is and why the project needs it.>
+
+1. Sign up / provision at <URL if well-known, else describe>
+2. <specific step to configure — create a project, app, database, etc.>
+3. Obtain: <credential names>
+4. Set env vars: `VAR_NAME=...`
+
+### <Next service>
+
+...
+
+## Local Setup
+
+\`\`\`bash
+<step-by-step commands from fresh clone to running locally>
+\`\`\`
+
+## Deployment Setup
+
+<What needs to be configured in the hosting environment the first time. If the project has no deployment pipeline, write: "No deployment pipeline is configured in this project." and stop.>
+```
+
+External services is the centerpiece. Cover every external account an engineer must create before the project runs.
+
+### ci-cd.md
+
+```markdown
+# CI/CD
+
+## Pipeline Overview
+
+<What triggers CI/CD — PR, push to main, tag. 1–2 sentences.>
+
+## Jobs
+
+### <job name> — `.github/workflows/<file>.yml`
+
+<What it runs and when.>
+
+- <step>: <command or purpose>
+- ...
+
+### <next job> — ...
+
+## Deployment Flow
+
+<Branch → environment mapping, manual steps, approvals.>
+
+## Secrets and Environments
+
+| Secret | Used by | Source |
+|--------|---------|--------|
+| `SECRET_NAME` | <job> | <where it comes from> |
+
+## Gotchas
+
+<Only if there are non-obvious facts — cache keys, manual retries, runner quirks. Omit the section if there are none.>
+```
+
+If the project has no CI/CD config, the entire file is:
+
+```markdown
+# CI/CD
+
+No CI/CD pipeline is configured in this project.
+```
+
+Do not invent one.
+
+### best-practices.md
+
+```markdown
+# Best Practices
+
+<2–3 sentences: how this project approaches quality — types, tests, linting, review.>
+
+## Practices
+
+### <Practice name>
+
+<1–2 sentences describing the practice.>
+
+**Example:** `path/to/file.ext:LNN-LNN`
+
+### <Next practice>
+
+...
+```
+
+Document practices the codebase *actually follows*. If TypeScript is strict, document it. If it's not, do not document "should be strict" — that is `/audit`'s job.
+
+### patterns.md
+
+```markdown
+# Patterns
+
+<2–3 sentences framing the dominant patterns.>
+
+## <Pattern name>
+
+<What it solves. 1–2 sentences.>
+
+**Where it appears:**
+- `path/to/file.ext:LNN`
+- `path/to/other.ext:LNN`
+
+**Shape:**
+
+\`\`\`<lang>
+<minimal code sketch showing the pattern, real code from the repo>
+\`\`\`
+
+## <Next pattern>
+
+...
+```
+
+Include project-specific patterns, not only textbook names. A new engineer should recognize these patterns when opening a file.
+
+---
+
+## Step 4 — Report to User
+
+List the files written, and any files skipped:
+
+```
+Regenerated:
+- docs/operational-documentation/architecture.md
+- docs/operational-documentation/first-time-setup.md
+- docs/operational-documentation/ci-cd.md
+- docs/technical-documentation/best-practices.md
+- docs/technical-documentation/patterns.md
+
+Skipped (not in scope): <list, or "none">
+```
+
+---
+
+## Constraints
+
+**DO:**
+- Write for human engineers — concise, direct, scannable
+- Cite a file path for every claim about the codebase
+- Use Mermaid for diagrams, in `architecture.md` only, one diagram per file
+- Overwrite only the five managed files that are in scope
+- Describe what exists in the codebase, not what should exist
+- Say "not configured" in one sentence when a section has nothing real to describe
+
+**DON'T:**
+- Create additional files or folders under `docs/`
+- Modify `docs/README.md` or any file outside `operational-documentation/` and `technical-documentation/`
+- Invent features, services, or pipelines that aren't in the codebase
+- Flag problems, gaps, or improvements — that belongs in `/audit`
+- Pad content with fluff, meta-commentary, or headers that restate titles in prose
+- Modify source code — the skill is read-only against the codebase
+- Produce multiple diagrams in `architecture.md`
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "This architecture has a flaw worth noting" — STOP. Docs describe, they don't critique. Tell the user to run `/audit` if it matters.
+- "I'll add a `security.md` too, it would help" — STOP. Five files, fixed. No invention.
+- "I'll update `docs/README.md` to reference the new files" — STOP. The skill owns the two managed subfolders only.
+- "There's no CI, I'll describe what it could look like" — STOP. If there's no CI, say so in one sentence.
+- "Let me add a 'Next Steps' or 'Further Reading' section" — STOP. Every section is specified. No extras.
+- "I'll write the patterns doc from memory without opening the code" — STOP. Every pattern cites real file paths.
+- "The user said minimal, but a second architecture diagram would really help" — STOP. One diagram per file.