Auto-detect project software stack and write a machine-readable stack context block into AGENTS.md. Runs during work-loop health check so Pi always knows the correct test runner, build tool, and conventions.
name stack-detect description Auto-detect project software stack and write a machine-readable stack context block into AGENTS.md. Runs during work-loop health check so Pi always knows the correct test runner, build tool, and conventions. version 1.0.0 metadata {"hermes":{"tags":["stack-detection","health-check","project-context","brownfield"],"related_skills":["dev-team/work-loop","dev-team/health-fix"]}} Stack Detect — Auto-Detect Project Software Stack Inspects the project's config files and package.json to determine the actual software stack, then writes (or updates) a
section in AGENTS.md. This ensures Pi subagents always use the correct test runner, build commands, and conventions — no guessing. Trigger Called by dev-team/work-loop Step 1 (Pre-Flight Health Check), before lint/TS checks. Runs once per work-loop session. Also callable on-demand: hermes chat -s dev-team/stack-detect Input {project_root} : working directory (default: current directory) Process 0. Guard — Check Project Exists test -f {project_root}/package.json If no package.json exists (greenfield vibe-loop, pre-scaffold): Log: "stack-detect: no package.json found — skipping (greenfield project)" Do NOT write to AGENTS.md Return early with: { "status" : "NO_STACK" , "reason" : "no package.json — project not yet scaffolded" } The calling skill (work-loop or vibe-loop) should treat NO_STACK as non-blocking and continue without stack context. Stack-detect will run again on the next work-loop invocation after the project is scaffolded.
<!-- BEGIN STACK DETECT --> <!-- END STACK DETECT --> <!-- BEGIN STACK DETECT --> <!-- END STACK DETECT -->jest in devDeps Jest CI=true npx jest karma.conf.* exists Karma npx karma start 3a. Detect Interactive Watch Mode (CRITICAL) Some frameworks run tests in watch mode by default, which hangs in non-interactive environments (Pi subagents, CI). Detect and neutralize: Framework Watch Mode Default? Fix Create React App ( react-scripts test ) YES — watch mode by default Prefix ALL test commands with CI=true CRACO ( craco test ) YES — inherits CRA behavior Prefix ALL test commands with CI=true Vitest NO — vitest run is non-interactive No fix needed ( vitest run not vitest ) Jest (standalone) NO — unless --watch flag No fix needed Rule: If react-scripts OR @craco/craco is in dependencies, ALL test commands MUST be prefixed with CI=true . This includes the single-file command and the full-suite command. Without this prefix, the test process will hang indefinitely waiting for keyboard input. Also detect: Test file pattern : check jest.config or vitest.config for testMatch / include patterns Test environment : check for jsdom , happy-dom , node in config Setup files : check for setupFiles , setupFilesAfterFramework , globalSetup 4. Detect Framework & Build Tool Check Framework react-scripts in deps Create React App @craco/craco in deps CRA + CRACO override next in deps Next.js vite in deps Vite webpack.config.* exists Webpack (manual) express in deps Express.js backend @aws-cdk in deps AWS CDK infra 5. Detect Database & ORM Check Database Tool knex in deps Knex.js (check knexfile for migration path) prisma in deps Prisma (check prisma/schema.prisma ) typeorm in deps TypeORM sequelize in deps Sequelize pg in deps PostgreSQL driver mysql2 in deps MySQL driver For Knex: detect migration directory and naming convention by reading existing migrations. 6. Detect TypeScript Config ls {project_root}/tsconfig*.json Note which configs exist (e.g., tsconfig.json , tsconfig.server.json , tsconfig.app.json ) and which is used for the build/typecheck. 7. Write Stack Block to AGENTS.md Look for an existing
/
block in AGENTS.md. If found, replace it. If not, insert it before the first
heading (so it's near the top). Template:
Auto-generated — do not edit manually. Re-run
stack-detectto refresh. | Category | Tool | Command | |----------|------|---------| | Package manager | {pkg _manager} |{install_ cmd}| | Test runner | {test _runner} |{test_ cmd}| | Test (single file) | {test runner} |{test_ single _cmd} {file}| | Build | {build tool} |{build_cmd}| | Dev server | {dev _tool} |{dev_ cmd}| | Lint | {linter} |{lint_cmd}| | TypeCheck | tsc |{tsc_cmd}| | Database | {db _tool} | migrations in{migration_ path}| | Migration naming | {migration _pattern} | e.g.YYYYMMDDHHMMSS_ description.ts|
{test_pattern}{test_env}
(jsdom/node/happy-dom){setup_files}Config files:
{tsconfig_list}
{test_single_cmd} {file}{full_test_cmd}{wrong_test_runner}
— this project uses
{test_runner}npm test
without CI=true if this is a CRA/CRACO project — it will hang in watch modeIf CI=true is in the commands above, it is REQUIRED — do not omit it