Stack Detect

1. Detect Package Manager Check which lockfile exists: File Package Manager Install Command pnpm-lock.yaml pnpm pnpm install yarn.lock yarn yarn package-lock.json npm npm install bun.lockb bun bun install
2. Read package.json Scripts cat {project_root}/package.json | jq '.scripts' Extract the key commands: test script → test command (e.g., craco test , jest , vitest , mocha ) build script → build command start / dev script → dev server command lint script → lint command
3. Detect Test Runner Priority order — first match wins: Priority order — first match wins: Check Detection Test Command scripts.test contains jest or craco test or react-scripts test Jest (possibly via CRA/craco) CI=true npx jest scripts.test contains vitest Vitest npx vitest run scripts.test contains mocha Mocha npx mocha vitest.config.* exists Vitest npx vitest run jest.config.* exists Jest CI=true npx jest .babelrc or babel.config.*

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:

Project Stack (auto-detected by stack-detect)

Auto-generated — do not edit manually. Re-run stack-detect to 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 |

Key Conventions

Test file location: {test_pattern}

Test environment: {test_env} (jsdom/node/happy-dom)

Setup files: {setup_files}

Config files: {tsconfig_list}

Pi Instructions

Run single test file with: {test_single_cmd} {file}

Run full suite with: {full_test_cmd}

NEVER use {wrong_test_runner} — this project uses {test_runner}

NEVER run bare npm test without CI=true if this is a CRA/CRACO project — it will hang in watch mode

If CI=true is in the commands above, it is REQUIRED — do not omit it

8. Verify Read back the written block and confirm it parses correctly. Log the detected stack summary. Output Returns a structured object to the calling skill: { "test_cmd" : "CI=true npx jest" , "test_single_cmd" : "CI=true npx jest --testPathPattern" , "build_cmd" : "npm run build" , "lint_cmd" : "npx eslint src//*.ts src//*.tsx --quiet" , "tsc_cmd" : "npx tsc -p tsconfig.server.json --noEmit" , "migration_path" : "database/migrations/" , "migration_pattern" : "YYYYMMDDHHMMSS_description.js" } The work-loop uses test_cmd and test_single_cmd in Step 7 (Pi dispatch) instead of hardcoded runner names. Dependencies External: jq (for parsing package.json), ls , cat Files read: package.json , config files, existing migrations Files written: AGENTS.md (stack block only, between markers)