playbooks

home / skills / gruckion / marathon-ralph / project-detection

project-detection skill

/skills/project-detection

This skill detects project type, package manager, and monorepo layout to provide cached, correct commands for builds, tests, and linting.

npx playbooks add skill gruckion/marathon-ralph --skill project-detection

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
4.3 KB
---
name: project-detection
description: Detects project type, package manager, and monorepo structure. Returns correct commands for test/build/lint/dev. Run at project initialization and cache results in state. Use before running any build/test commands.
---

# Project Detection

Detects project configuration and provides standardized commands. Run once at init, cache in state file.

## Usage

Run the detection script from the project root:

```bash
./marathon-ralph/skills/project-detection/scripts/detect.sh /path/to/project
```

Returns JSON:

```json
{
  "language": "node",
  "packageManager": "bun",
  "monorepo": {
    "type": "turbo",
    "workspaces": ["apps/web", "apps/api", "packages/shared"]
  },
  "commands": {
    "install": "bun install",
    "dev": "bun run dev",
    "build": "bun run build",
    "test": "bun run test",
    "testWorkspace": "bun run --filter={workspace} test",
    "lint": "bun run lint",
    "typecheck": "bun run check-types"
  }
}
```

## Caching Results

After detection, store in marathon state file under `project` key:

```json
{
  "project": {
    "language": "node",
    "packageManager": "bun",
    "monorepo": { "type": "turbo", "workspaces": [...] },
    "commands": { ... },
    "detectedAt": "2024-01-03T12:00:00Z"
  }
}
```

## Using Cached Commands

When running commands, always check state first:

1. Read `project.commands` from state  
2. If not present, run detection script  
3. Use the appropriate command from the cache  

### For Monorepos

When tests/builds need to target a specific workspace:

```bash
# Use testWorkspace with the workspace name
bun run --filter=web test

# Or for all workspaces
turbo run test
```

### Command Selection Priority

1. Use cached command from state  
2. If no cache, run detection  
3. If detection fails, fall back to reference patterns  

## Detection Logic

### Package Manager Detection (by lock file)

| Lock File                      | Package Manager | Install               | Run        |
|--------------------------------|-----------------|-----------------------|------------|
| `bun.lock` or `bun.lockb`      | bun             | `bun install`         | `bun run`  |
| `pnpm-lock.yaml`               | pnpm            | `pnpm install`        | `pnpm run` |
| `yarn.lock`                    | yarn            | `yarn install`        | `yarn`     |
| `package-lock.json`            | npm             | `npm install`         | `npm run`  |

### Monorepo Detection

| Config File                        | Monorepo Type         |
|------------------------------------|-----------------------|
| `turbo.json`                       | Turborepo             |
| `nx.json`                          | Nx                    |
| `lerna.json`                       | Lerna                 |
| `pnpm-workspace.yaml`              | pnpm workspaces       |
| `package.json` with `workspaces`   | npm/yarn workspaces   |

### Language Detection

| Indicator                             | Language |
|---------------------------------------|----------|
| `package.json`                        | Node.js  |
| `pyproject.toml`, `setup.py`          | Python   |
| `go.mod`                              | Go       |
| `Cargo.toml`                          | Rust     |
| `build.gradle`, `pom.xml`             | Java     |

## Python Project Commands

For Python projects:

| Tool        | Install                                   | Run Script              | Test                  |
|-------------|-------------------------------------------|-------------------------|-----------------------|
| poetry      | `poetry install`                          | `poetry run {script}`   | `poetry run pytest`   |
| poetry+poe  | `poetry install`                          | `poe {task}`            | `poe test`            |
| pip + venv  | `pip install -r requirements.txt`         | `python -m {module}`    | `pytest`              |
| uv          | `uv pip install -r requirements.txt`      | `uv run {script}`       | `uv run pytest`       |
| pipenv      | `pipenv install`                          | `pipenv run {script}`   | `pipenv run pytest`   |

**Note:** If `[tool.poe.tasks]` exists in `pyproject.toml`, poe commands are preferred.

## Reference Files

- [node.md](node.md) - Node.js patterns and commands
- [python.md](python.md) - Python patterns and commands
- [monorepo.md](monorepo.md) - Monorepo-specific patterns

Overview

This skill detects a project's language, package manager, and monorepo structure, then generates standardized commands for install, dev, build, test, lint, and typecheck. It runs once at initialization, caches results in the marathon state, and is intended to be consulted before running any build or test commands. The cached JSON ensures consistent command selection across CI and local workflows.

How this skill works

The detection script inspects repository files (lockfiles, package.json, pyproject.toml, go.mod, Cargo.toml, monorepo config files) to infer language, package manager, and monorepo type. It maps findings to a canonical set of commands (install, run/dev, build, test, lint, typecheck) and returns JSON. Results are written to the marathon state under the project key with a timestamp. The skill is read from state before executing commands and will re-run detection if no cache exists.

When to use it

  • Run at project initialization to create a cached command set.
  • Before any build, test, lint, or dev task to ensure correct commands are used.
  • In CI pipeline setup to pick the right install and run commands for each job.
  • When onboarding to a new repo or switching branches that may change project layout.
  • Before running workspace-targeted operations in monorepos.

Best practices

  • Always read project.commands from state and only re-run detection when the cache is missing or stale.
  • Commit or persist the state file where CI and local tooling can access it to avoid repeated detection overhead.
  • Prefer workspace-targeted commands (testWorkspace) for monorepos to limit scope and speed up runs.
  • Fallback to reference patterns only if detection fails; surface detection failures to the user for corrective action.
  • Update detection logic if you add new package managers or monorepo tools to the repo.

Example use cases

  • Detect package manager (bun/pnpm/yarn/npm) and return the exact install and run commands for local development.
  • Identify a Turborepo and produce workspace-aware test/build commands like turbo run test or filtered runner commands.
  • Detect a Python project using poetry or poe and return poetry install + poe test when appropriate.
  • Cache commands after first run so CI jobs read the same commands without re-detection.
  • Select pnpm workspace commands when pnpm-workspace.yaml or package.json workspaces are present.

FAQ

What happens if detection returns incorrect commands?

If detection is wrong, update or delete the cached project entry so the script can re-run; the skill falls back to reference patterns if detection fails.

How does the skill handle monorepos?

It detects monorepo type (turborepo, nx, lerna, pnpm workspaces, npm/yarn workspaces) and exposes workspace-aware commands and a testWorkspace template for targeted operations.