@piagent/platform 1.0.0

package/scripts/verify-vercel-link.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const expected = Object.freeze({
+  projectId: "prj_k3yqhdVXhwJWH8KC0J17UDulsVpG",
+  orgId: "team_XYGedgJi8GJXu25Fg2J7Bz0Q",
+  projectName: "pi-agent"
+});
+
+function fail(message) {
+  process.stderr.write(`FAIL: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArguments(values) {
+  let projectFile = path.join(repositoryRoot, "docs-site", ".vercel", "project.json");
+  let provided = false;
+  for (let index = 0; index < values.length; index += 1) {
+    const option = values[index];
+    if (option === "-h" || option === "--help") {
+      process.stdout.write("Usage: node scripts/verify-vercel-link.mjs [--project-file <path>]\n");
+      process.stdout.write("Verify that local Vercel metadata targets the canonical pi-agent project.\n");
+      process.exit(0);
+    }
+    if (option !== "--project-file") fail(`unknown option ${option}`);
+    if (provided) fail("duplicate option --project-file");
+    const value = values[index + 1];
+    if (!value || value.startsWith("--")) fail("--project-file requires a value");
+    projectFile = path.resolve(value);
+    provided = true;
+    index += 1;
+  }
+  return projectFile;
+}
+
+const projectFile = parseArguments(process.argv.slice(2));
+let stat;
+try {
+  stat = fs.lstatSync(projectFile);
+} catch (error) {
+  fail(`Vercel project metadata is missing at ${projectFile}; run: vercel link --cwd docs-site --project pi-agent`);
+}
+if (stat.isSymbolicLink() || !stat.isFile()) fail("Vercel project metadata must be a regular, non-symlink file");
+if (stat.size < 2 || stat.size > 16 * 1024) fail("Vercel project metadata has an unexpected size");
+
+let actual;
+try {
+  actual = JSON.parse(fs.readFileSync(projectFile, "utf8"));
+} catch (error) {
+  fail(`Vercel project metadata is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+}
+if (!actual || Array.isArray(actual) || typeof actual !== "object") fail("Vercel project metadata must be a JSON object");
+
+for (const [key, value] of Object.entries(expected)) {
+  if (actual[key] !== value) {
+    fail(`Vercel ${key} is ${JSON.stringify(actual[key] ?? null)}; expected ${JSON.stringify(value)}. Relink with: vercel link --cwd docs-site --project pi-agent`);
+  }
+}
+
+process.stdout.write(`PASS: Vercel link targets ${expected.projectName} (${expected.projectId})\n`);

package/templates/global/mcp.json

@@ -0,0 +1,9 @@
+{
+  "settings": {
+    "toolPrefix": "server",
+    "directTools": false,
+    "idleTimeout": 10,
+    "outputGuard": true
+  },
+  "mcpServers": {}
+}

package/templates/global/settings.json

@@ -0,0 +1,37 @@
+{
+  "defaultProjectTrust": "ask",
+  "defaultProvider": "openai-codex",
+  "defaultModel": "gpt-5.5",
+  "defaultThinkingLevel": "xhigh",
+  "showCacheMissNotices": true,
+  "enabledModels": [
+    "openai-codex/gpt-5.3-codex-spark:minimal",
+    "openai-codex/gpt-5.4-mini:minimal",
+    "openai-codex/gpt-5.4:xhigh",
+    "openai-codex/gpt-5.5:xhigh",
+    "openai-codex/gpt-5.6-luna:xhigh",
+    "openai-codex/gpt-5.6-sol:xhigh",
+    "openai-codex/gpt-5.6-terra:xhigh",
+    "anthropic/claude-haiku-4-5:low",
+    "anthropic/claude-sonnet-4-5:high",
+    "anthropic/claude-sonnet-4-6:max",
+    "anthropic/claude-sonnet-5:xhigh",
+    "anthropic/claude-opus-4-5:xhigh",
+    "anthropic/claude-opus-4-6:max",
+    "anthropic/claude-opus-4-7:xhigh",
+    "anthropic/claude-opus-4-8:xhigh",
+    "anthropic/claude-fable-5:xhigh"
+  ],
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  },
+  "packages": [
+    "__PIAGENT_PACKAGE_SOURCE__"
+  ],
+  "skills": [
+    "~/.claude/skills",
+    "~/.codex/skills"
+  ]
+}

package/templates/project/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "settings": {
+    "toolPrefix": "server",
+    "directTools": false,
+    "idleTimeout": 10,
+    "outputGuard": true
+  },
+  "mcpServers": {}
+}

package/templates/project/.pi/context-index.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "projectId": "replace-me",
+  "profileMode": "generic",
+  "source": "manual",
+  "summary": "Pending. Run /onboard-project after login/model selection to generate the compact project context index.",
+  "generatedAt": "not-configured",
+  "updatedAt": "not-configured",
+  "policy": {
+    "enabled": true,
+    "path": ".pi/context-index.json",
+    "writePolicy": "onboarding-record",
+    "requireCitations": true,
+    "maxNodes": 120,
+    "maxEdges": 240,
+    "includeTechStack": true,
+    "includeMemoryPointers": true
+  },
+  "nodes": [],
+  "edges": [],
+  "citations": [],
+  "warnings": [
+    "context index pending; run /onboard-project"
+  ]
+}

package/templates/project/.pi/gitignore.template

@@ -0,0 +1,22 @@
+# Pi local runtime
+piagent-state/
+task-inbox/
+todos/
+sessions/
+session-control/
+cache/
+.pi-subagents/
+progress.md
+benchmarks/
+npm/
+git/
+trust.json
+auth.json
+memory/MEMORY.md
+memory/memory_summary.md
+memory/state.sqlite
+memory/raw_memories.md
+memory/rollout_summaries/
+memory/extensions/ad_hoc/
+memory/local/
+memory/.git/

package/templates/project/.pi/mcp.json

@@ -0,0 +1,9 @@
+{
+  "settings": {
+    "toolPrefix": "server",
+    "directTools": false,
+    "idleTimeout": 10,
+    "outputGuard": true
+  },
+  "mcpServers": {}
+}

package/templates/project/.pi/memory/MEMORY.md

@@ -0,0 +1,11 @@
+# Project Memory
+
+Durable project memory for Pi Agent Platform.
+
+Rules:
+
+- Store only stable preferences, decisions, project conventions, lessons, and open loops.
+- Do not store secrets, credentials, raw customer data, or large source excerpts.
+- Treat memory as hints; verify against the repository before editing.
+
+## Entries

package/templates/project/.pi/memory/memory_summary.md

@@ -0,0 +1,9 @@
+v1
+
+# Memory Summary
+
+- Status: initialized
+- Scope: project
+- Policy: explicit durable notes only; repository files remain source of truth.
+
+Use this file as a compact memory index. Keep it short and update only with durable, verified context.

package/templates/project/.pi/piagent-profile.json

@@ -0,0 +1,107 @@
+{
+  "schemaVersion": 1,
+  "projectId": "replace-me",
+  "displayName": "Replace Me",
+  "mode": "generic",
+  "rootMarkers": [
+    "AGENTS.md",
+    "README.md"
+  ],
+  "protectedPaths": [
+    ".git/**",
+    "**/auth.json",
+    "**/.env",
+    "**/.env.*"
+  ],
+  "requiredContext": [
+    "AGENTS.md",
+    ".pi/project-context.md",
+    "README.md"
+  ],
+  "verifyCommands": {
+    "docsOnly": [
+      "test -s README.md"
+    ],
+    "source": [
+      "echo 'Configure verify command in .pi/piagent-profile.json'"
+    ]
+  },
+  "mcpCapabilities": [
+    "filesystem-readonly",
+    "filesystem-write",
+    "shell",
+    "memory"
+  ],
+  "capabilityPacks": [
+    {
+      "name": "engineering-base",
+      "version": "0.1.0"
+    }
+  ],
+  "capabilityPolicy": {
+    "allowedOwners": [
+      "platform-maintainers"
+    ],
+    "allowedLifecycles": [
+      "experimental"
+    ],
+    "allowedFilesystemRead": [
+      "**/*"
+    ],
+    "allowedFilesystemWrite": [
+      "**/*"
+    ],
+    "allowedNetworkDomains": [],
+    "allowedExternalActions": []
+  },
+  "memory": {
+    "enabled": true,
+    "mode": "manual",
+    "scope": "project",
+    "summaryFile": ".pi/memory/memory_summary.md",
+    "handbookFile": ".pi/memory/MEMORY.md",
+    "localDir": ".pi/memory/local",
+    "readBeforeTask": true,
+    "writePolicy": "explicit-only",
+    "maxInjectedChars": 4000,
+    "externalPackages": []
+  },
+  "contextIndex": {
+    "enabled": true,
+    "path": ".pi/context-index.json",
+    "writePolicy": "onboarding-record",
+    "requireCitations": true,
+    "maxNodes": 120,
+    "maxEdges": 240,
+    "includeTechStack": true,
+    "includeMemoryPointers": true
+  },
+  "orchestration": {
+    "defaultMode": "solo-first",
+    "maxConcurrentSubagents": 2,
+    "defaultReviewLenses": [
+      "correctness",
+      "tests",
+      "scope"
+    ],
+    "fieldGuide": {
+      "enabled": true,
+      "path": ".pi/memory/MEMORY.md",
+      "maxLines": 80,
+      "writePolicy": "explicit-only",
+      "readBeforeTask": true
+    }
+  },
+  "techStack": {
+    "provider": "context7",
+    "manifest": ".pi/tech-stack.json",
+    "contextDir": ".pi/tech-context",
+    "roles": {}
+  },
+  "runtimePolicy": {
+    "execPolicy": "enforce",
+    "contextBudget": "enforce",
+    "toolRegistry": "advisory",
+    "finalGate": "enforce"
+  }
+}

package/templates/project/.pi/project-context.md

@@ -0,0 +1,30 @@
+# Project Context
+
+## Status
+
+- Generated: not yet
+- Profile: see `.pi/piagent-profile.json`
+- Model/pass: run `/onboard-project` after Pi login and model selection
+- Scope: pending
+
+## Purpose
+
+This file is the reusable project context snapshot for Pi Agent Platform.
+
+Before the first real implementation task in this project:
+
+1. Open Pi in the project.
+2. Run `/login` if needed.
+3. Select the intended provider/model.
+4. Run `/onboard-project`.
+
+The selected model should inspect the project read-only, then replace this file with a concise project map, required context, verification matrix, and high-risk areas.
+
+## Update triggers
+
+Regenerate with `/onboard-project` when:
+
+- source layout changes;
+- architecture or domain ownership changes;
+- test/build commands change;
+- auth/data/migration/provider policy changes.

package/templates/project/.pi/settings.json

@@ -0,0 +1,17 @@
+{
+  "defaultProjectTrust": "ask",
+  "defaultThinkingLevel": "xhigh",
+  "showCacheMissNotices": true,
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  },
+  "packages": [
+    "__PIAGENT_PACKAGE_SOURCE__"
+  ],
+  "skills": [
+    ".claude/skills",
+    ".codex/skills"
+  ]
+}

package/templates/project/.pi/task-contract.template.json

@@ -0,0 +1,74 @@
+{
+  "taskId": "TASK-0001",
+  "summary": "Replace with one-sentence task outcome.",
+  "riskLane": "normal",
+  "expectedOutput": "Replace with exact artifact or behavior expected.",
+  "acceptanceCriteria": [
+    "Replace with pass/fail criterion."
+  ],
+  "scope": [
+    "replace/with/allowed/path/**"
+  ],
+  "outOfScope": [
+    "Replace with explicit non-goal."
+  ],
+  "protectedPaths": [],
+  "requiredContext": [],
+  "contextManifest": [],
+  "memoryCitations": [],
+  "mcpCapabilities": [],
+  "verifyCommands": [
+    "Replace with verify command."
+  ],
+  "workPlan": [
+    {
+      "id": "plan",
+      "title": "Confirm scope, context, acceptance criteria, and verify gate before editing.",
+      "role": "parent",
+      "mode": "read-only",
+      "status": "pending"
+    },
+    {
+      "id": "implement",
+      "title": "Implement the approved bounded change.",
+      "role": "parent",
+      "mode": "single-writer",
+      "status": "pending",
+      "dependsOn": [
+        "plan"
+      ]
+    },
+    {
+      "id": "review",
+      "title": "Run explicit review lenses against the diff and verify evidence.",
+      "role": "piagent-reviewer",
+      "mode": "review",
+      "status": "pending",
+      "dependsOn": [
+        "implement"
+      ]
+    }
+  ],
+  "reviewLenses": [
+    "correctness",
+    "tests",
+    "scope"
+  ],
+  "orchestration": {
+    "mode": "solo-first",
+    "subagents": "not-used",
+    "reason": "Task starts in solo-first mode; use bounded subagents only for independent scout, planning, or review work.",
+    "fieldGuidePath": ".pi/memory/MEMORY.md",
+    "modelRoles": {
+      "planner": "Use the strongest available model for decomposition, architecture, risk, and acceptance criteria.",
+      "worker": "Use the fastest reliable model for a bounded, already-planned single write set.",
+      "reviewer": "Use a model or thinking setting decorrelated from the worker when review quality matters.",
+      "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
+    }
+  },
+  "changedFiles": [],
+  "verifyEvidence": [],
+  "trace": {
+    "outcome": "pending"
+  }
+}

package/templates/project/.pi/tech-context/README.md

@@ -0,0 +1,7 @@
+# Tech context snapshots
+
+This directory stores concise Context7 snapshots for the selected project tech stack.
+
+Use `/profile tech setup` to select the profile and role tech stack. After reading current framework/library docs through Context7, record a short summary with `piagent_profile_tech_context_record`.
+
+Do not store secrets, tokens, sessions, credentials, or long copied documentation here.

package/templates/project/.pi/tech-stack.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "provider": "context7",
+  "profile": "generic",
+  "roles": {},
+  "selected": [],
+  "contextDir": ".pi/tech-context",
+  "createdAt": "not-configured",
+  "updatedAt": "not-configured"
+}

package/templates/project/AGENTS.md

@@ -0,0 +1,34 @@
+# Project Agent Instructions
+
+## Operating model
+
+This project uses Pi Agent Platform.
+
+Before implementation:
+
+1. Load `.pi/piagent-profile.json` with `piagent_context`.
+2. If `.pi/project-context.md` still says "Generated: not yet", run `/onboard-project` after login/model selection before the first implementation task.
+3. Check `.pi/context-index.json` with `/context-index` or `piagent_context_index_status` when available; use it only as an advisory navigation map.
+4. Read `.pi/project-context.md` and required context files listed in the profile; use `piagent_context_budget` for large files.
+5. Check project memory with `piagent_memory_status` when relevant; memory is advisory, source files are authoritative.
+6. Start source-changing work with `piagent_task_start`.
+7. Respect protected paths.
+8. Use `piagent_exec_policy_check` before high-impact or complex shell commands.
+9. Use `piagent_tool_policy_check` before non-piagent MCP/app tools.
+10. Use MCP/tools only when declared in profile.
+11. Use `piagent_usage_snapshot` or `/piagent-usage` when the user asks about token/context usage or session follow-up.
+12. Record context/verify/trace with `piagent_context_record`, `piagent_verify_record`, and `piagent_trace_record`. Passing verify evidence must be the exact command from `task.verifyCommands`.
+13. Run `piagent_task_gate_check` before DONE.
+14. For unclear tasks, use `/discuss` first; do not implement while requirements are unresolved.
+15. For external source repos, use `piagent-source-cache` and read targeted files only.
+16. For medium/large tasks, auto-delegate independent read-only scout/planning/review work to `piagent-scout`, `piagent-planner`, `piagent-reviewer`, or `piagent-oracle` when `pi-subagents` is available. Do not require the user to type `/run` for normal task orchestration.
+17. Keep implementation single-writer by default. Use parallel writers only with explicit user approval or safe worktree isolation and disjoint write sets.
+18. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns, review loops, native supervisor coordination, and safety boundaries.
+
+## Review
+
+Use `REVIEW_GUIDELINES.md` when reviewing code in this project.
+
+## Secrets
+
+Do not commit OAuth tokens, API keys, `.env`, `auth.json`, session files, `.pi/memory/MEMORY.md`, `.pi/memory/memory_summary.md`, or `.pi/memory/local/`.

package/templates/project/REVIEW_GUIDELINES.md

@@ -0,0 +1,23 @@
+# Project Review Guidelines
+
+Use this file as project-local review policy for Pi `/review` or piagent review prompts.
+
+## Review priorities
+
+1. Correctness and data integrity.
+2. Security and secret handling.
+3. Contract compatibility with upstream/downstream consumers.
+4. Minimal, maintainable diff.
+5. Tests and verification evidence.
+
+## Required review output
+
+- Findings with severity.
+- File/line references when possible.
+- Missing verification.
+- Risk of regression.
+- Recommendation: approve / request changes / block.
+
+## Project-specific additions
+
+Add domain rules here after linking the project.

package/types/pi-runtime-shims.d.ts

@@ -0,0 +1,13 @@
+declare module "@earendil-works/pi-coding-agent" {
+  export type ExtensionAPI = any;
+  export type ExtensionContext = any;
+  export function isToolCallEventType(toolName: string, event: any): boolean;
+}
+
+declare module "@earendil-works/pi-ai" {
+  export const StringEnum: any;
+}
+
+declare module "typebox" {
+  export const Type: any;
+}