Detect Stack

Detect Stack

This is the foundation skill. Every other webdev skill that runs a project command (run-tests, commit, new-feature, …) resolves the command through this plugin's scripts rather than hardcoding npm test or phpunit.

Supported stacks. Auto-detection covers JS/TS (npm/pnpm/yarn/bun) and PHP (Composer). Any other stack works too — pin its commands in .claude/webdev.json and they're used verbatim. The detector intentionally stays narrow: an undetected stack falls through to the gaps path and asks, rather than guessing a command it can't stand behind.

Resolve the stack profile

Run the bundled script in the project root:

${CLAUDE_PLUGIN_ROOT}/scripts/detect-stack

The script:

1. Reads .claude/webdev.json at the project root. Any key present there is authoritative.
2. Detects whatever is not pinned from the repo files.
3. Applies commandPrefix to detected commands only.
4. Prints a JSON profile to stdout.

commandPrefix is prepended to every detected command — this is how containerized setups work (e.g. a DDEV project sets "commandPrefix": "ddev exec" so a detected pnpm test runs as ddev exec pnpm test). Pinned commands are used verbatim — never apply the prefix to them. A pinned command written in webdev.json is complete, prefix included. If a project pins everything, detection is skipped.

{
  "packageManager": "pnpm",
  "install": "pnpm install",
  "test": "pnpm test",
  "format": "pnpm run format",
  "lint": "pnpm run lint",
  "typecheck": "pnpm exec tsc --noEmit",
  "dev": "pnpm dev",
  "build": "pnpm build",
  "commandPrefix": "",
  "branchPrefixes": ["feature", "fix", "refactor", "docs", "chore", "review"]
}

Resolve a single command

For command-running skills, use the companion script to avoid re-deriving commands:

${CLAUDE_PLUGIN_ROOT}/scripts/resolve-command test
${CLAUDE_PLUGIN_ROOT}/scripts/resolve-command format

This prints the resolved command string for that key, with commandPrefix applied when appropriate. Exit codes let a caller branch instead of guessing:

| Code | Meaning | Caller action | |------|---------|---------------| | 0 | Command resolved (printed to stdout) | run it | | 2 | .claude/webdev.json is invalid (bad JSON or not an object) | abort — fix config | | 3 | No such command for this stack (legitimately absent) | clean N/A skip for optional gates | | 4 | Ambiguous package manager (multiple JS lockfiles, not pinned) | abort — pin packageManager |

Only exit 3 is a safe skip. 2/4 mean the setup is unsafe, so an optional gate (format/lint/build/typecheck/migrationStatus) must abort rather than silently treat it as N/A. A command pinned in webdev.json is returned verbatim even under a 4 ambiguity, since it doesn't depend on the detected manager.

When detection is ambiguous

If the script returns a non-empty gaps array, state what you found and ask — don't run a guessed command. Offer to write the resolved values into .claude/webdev.json so the next run is deterministic.

Output

Report a concise stack profile the caller can act on:

• Source: webdev.json | detected | mixed (which keys came from where)
• Package manager, install
• Test command, format command, lint command, type-check command (or N/A)
• Framework (+ version if known) · Migration-status command (or N/A)
• Dev command, build command
• Workspace/package (monorepos only): which package the profile applies to
• Command prefix (if any)
• Branch prefixes allowed
• Gaps / ambiguities: anything the script couldn't resolve, with a recommended next step (usually: pin it in webdev.json)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jaballer
• Source: jaballer/claude-webdev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.