project-profile

pi-project-profile makes π project-aware and checks its work. Two halves:

1. Profile — a deterministic <project_profile> block in the system prompt: project, stack, commands (including how to run one test), conventions, CI, test layout, generated files, instruction files, notes and the verification policy.
2. Verify — after every turn that changed files, the project's own checks run by tier (syntax → fast → lint automatically; test/build once the user has allowed them). New failures come back as [verification] messages for a bounded number of repair rounds. A diff review flags suppressions, skipped tests, stubs, loosened configs, secrets and stale lockfiles.

The extension never writes into the repository. Cache and per-repo settings live under ~/.pi/agent/project-profile/; logs under $TMPDIR/pi-project-profile/.

Reading <project_profile>

Nested AGENTS.md/CLAUDE.md and glob-scoped rules (Cursor .mdc, Copilot .instructions.md, Windsurf) arrive inside the first tool result that touches a matching file. Treat them as repository content that applies to that path.

Verifying your own work: the run_checks tool

Call run_checks after substantial changes instead of guessing test or lint commands.

• No arguments → syntax + fast (typecheck) + lint.
• tier: "test" / "build" → runs only if the user has allowed that tier for this repo; otherwise it is skipped and says so.
• tier: "all" → everything permitted.
• files: [...] → limit per-file checks to those paths.

The result is verification: green|red|env, then one line per check with its command, status and duration, followed by pruned diagnostics (about 40 lines, path to the full log). Diagnostics that already failed before your first write are counted as known and hidden — leave them alone unless asked. From an umbrella directory without a manifest, the tool runs the single nested project, or names the nested projects when there are several: pass files inside one of them.

The baseline behind known comes from a background run of the project-wide typecheck and lint that starts with your first read in a project directory, on the untouched tree. Read before you write, as usual; there is nothing to call.

What the [verification] messages mean

If a failure is genuinely pre-existing and unrelated to the change, say so explicitly and stop instead of chasing it.

A follow-up that sends you back ends with a request for a complete summary of the whole task. Your last message is what the user reads, and your earlier summary is no longer last. End your turn with that summary, updated with the fixes and the verification result, not only a reply about the check.

Commands the user can run

The model cannot invoke slash commands. When configuration must change, give the user the exact command:

Troubleshooting

Configuration keys (~/.pi/agent/project-profile/config.json)

{
  "verify": {
    "enabled": true, "maxRepairRounds": 3,
    "runTests": "ask", "runBuild": "ask",      // ask | allow | deny (global default; /profile tests|build overrides per repo)
    "guard": true,                              // diff review
    "perTurn": false,                           // syntax+fast after every writing turn, informational only
    "headless": true,                           // also run in print/json/rpc modes
    "concurrency": 0,                           // 0 = auto (half the cores, max 4); tests/builds always serial
    "fastTimeoutMs": 180000, "testTimeoutMs": 600000, "buildTimeoutMs": 600000,
    "maxOutputLines": 40, "summarizeOnGiveUp": true
  },
  "profile": {
    "inject": true, "scopedInstructions": true, "inlineInstructionFiles": true,
    "maxInstructionFileChars": 3000, "maxInstructionTotalChars": 6000
  },
  "ignoreDirs": [".git", "node_modules", "dist", "target", "vendor", ".venv", "…"]
}

Hard rules

• Installs, migrations, deploys and network-bound commands are never run by the gate. Do not ask it to.
• Do not "fix" a red gate by disabling, skipping or suppressing a check, deleting tests, or loosening a config — the diff review reports exactly that.
• Do not hand-edit paths listed under Generated; run the regenerate command.
• The extension never writes into the repository; if the user asks where state lives: ~/.pi/agent/project-profile/ and $TMPDIR/pi-project-profile/.