Project Intelligence

Project Intelligence translates a code diff into affected product flows, explains the selection, and runs only the selected browser scenarios.

git diff -> affected flows -> executable scenarios -> evidence -> bounded repair -> PR

Requirements

• Node.js 22.12 or newer
• Git
• Chromium installed by Playwright (npx playwright install chromium)
• Optional integrations: gh, Claude Code or Codex, webhook credentials

Install and build

npm ci
npm run typecheck
npm test
npm run build
npm link

The package exposes the pi binary and its TypeScript API.

Register a repository

Run a dry proposal first. Existing .proj-intel files are never overwritten by registration.

pi register --repo /path/to/product
pi register --repo /path/to/product --write
pi register --repo /path/to/product --explore-url http://localhost:3000 --write

Commit and review the generated graph. After committing it on a branch, pi register --pr opens the review PR through gh.

.proj-intel/
  config.yaml
  flows/*.md
  screens/*.md
  apis/*.md

A runnable flow uses the 테스트 or test section:

# Reservation cancel

## Path
[[dashboard]] -> [[cancel-confirm]] -> [[cancel-complete]]

## Related code
- `src/api/reservation.ts`

## Test
- browser: playwright
- entry: /reservations/123
- auth: required
- step: click [data-testid=cancel]
- step: expect Cancellation complete

Supported deterministic actions are click <selector>, fill <selector> = <value>, press <key>, wait <selector>, and expect <text>.

Default impact workflow

Use the PR base and head revisions. --explain prints the code/import/graph reason chain for every selected flow.

pi impact --repo /path/to/product --diff main..HEAD --explain
pi impact --repo /path/to/product --diff main..HEAD --json

Impact thresholds and typed-edge weights are repository settings:

impact:
  importer_hops: 2
  thresholds:
    must_run: 0.8
    maybe: 0.5
  edge_weights:
    navigates_to: 1
    uses_api: 1
    touches_code: 1
    contains_screen: 1

Run browser scenarios

pi run --repo /path/to/product --flow reservation-cancel --base-url http://localhost:3000
pi run --repo /path/to/product --all --base-url http://localhost:3000
pi run --repo /path/to/product --diff main..HEAD --base-url http://localhost:3000
pi run --repo /path/to/product --diff main..HEAD --run-maybe --base-url http://localhost:3000

must_run flows always run for diff selection. maybe flows run only with --run-maybe or browser.run_maybe: true. Relative entries require --base-url or browser.base_url. Authenticated flows require a Playwright-compatible --storage-state file.

Playwright is the default adapter. Puppeteer is selected with browser: puppeteer; set PI_PUPPETEER_EXECUTABLE when Chrome is not discoverable. Aside integrations inject AsideBrowserClient into AsideBrowserAdapter through the TypeScript API.

Every successful navigation and action captures a screenshot; failures attempt a best-effort diagnostic screenshot without replacing the primary error. Console, network, optional DOM, and a manifest are written under .proj-intel/evidence/. Inspect the latest result with:

pi status --repo /path/to/product
pi report --repo /path/to/product

Repair policy

Repairs run in detached temporary git worktrees. The caller supplies the task and connected-regression verification commands to repairFlow; the exact candidate patch is applied to the target repository only after those commands pass in a fresh verifier worktree and all limits are satisfied.

repair:
  max_attempts: 2
  max_files_changed: 5
  max_diff_lines: 150
  forbidden:
    - migrations/**
    - auth/**
    - billing/**

policies:
  payment:
    autofix: true
    automerge: false
    human_review: required

Use the exported repairFlow API with either the claude or codex agent. A dirty worktree, disabled policy, forbidden path, or exceeded diff limit escalates without applying a patch.

PR, review, merge, and notifications

The package exports:

• createEvidencePullRequest for gh pr create with cause, fix, E2E, and evidence sections
• mergePullRequestIfAllowed for E2E, approval, and optional CodeRabbit check enforcement
• SlackWebhookAdapter, DiscordWebhookAdapter, and TelegramAdapter

Credentials are constructor inputs or environment values owned by the caller; they are not stored in .proj-intel.

MCP and provider integrations

Start the stdio MCP server:

pi mcp

It exposes pi.flows, pi.impact, pi.run, pi.status, pi.register, and pi.report.

ProjectIntelligenceProvider.verify implements the Rich Parallel Agents contract with baseSha and headSha. flowsForScreenChanges and verifyFigmaScreenChanges map Figma screen identifiers to graph flows and E2E execution.

Reusable GitHub Action

Use the action in a product repository that has a committed .proj-intel graph. It always prints the explainable impact report and can optionally execute the selected browser scenarios.

permissions:
  contents: read

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      fetch-depth: 0
      persist-credentials: false
  - uses: agent-infra-for-justn/project-intelligence@1fc53bf9c2febcae6f388ff3b2f506aba510557d # action-v1.1.0
    with:
      diff: ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}
      execute: true
      run-maybe: false
      base-url: ${{ vars.PI_BASE_URL }}

repo selects a safe repository path relative to the workspace. storage-state is resolved by the CLI from the job working directory and accepts a path to a Playwright-compatible authentication state file. When execution is enabled, the action installs the matching Playwright Chromium build and writes evidence to a fresh runner-temporary root. evidence-dir is a safe relative subdirectory inside that root; the absolute path is exposed as the evidence-dir output. Browser evidence is uploaded even after a failed scenario as project-intelligence-evidence by default. Customize it with artifact-name and retention-days, or disable upload with upload-evidence: false. The action pins [email protected] by default and accepts another exact semantic version through package-version; package-tarball accepts a safe workspace-relative packed release candidate for CI validation.

CI and deployment

.github/workflows/project-intelligence.yml runs typechecking, tests, build, and PR/push impact analysis. Scheduled E2E runs when the repository variable PI_BASE_URL is configured.

Package preflight:

npm run typecheck
npm test
npm run build
npm pack --dry-run

Publishing requires an npm trusted-publisher mapping for this repository, the publish.yml workflow, and the protected npm GitHub environment. The release tag must exactly equal v${package.version}. Node 24/npm 11 satisfy npm's OIDC trusted-publishing requirements; eligible public GitHub releases receive npm provenance automatically. Disable legacy npm publish tokens after the trusted publisher is active.