@piagent/platform 1.0.0

package/packages/piagent-core/security/sensitive-data.js

@@ -0,0 +1,187 @@
+const REDACTION = "[REDACTED_SECRET]";
+
+const TOKEN_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bgh[opsru]_[A-Za-z0-9_]{20,}\b/g,
+  /\bsk-(?:(?:proj|svcacct|admin|ant)-)?[A-Za-z0-9_-]{20,}\b/g,
+  /\bsk_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAIza[0-9A-Za-z_-]{20,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g
+];
+
+const CONNECTION_URL_PATTERN = /\b((?:https?|ftp|postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/"']+:)([^@\s/"']+)(@[^\s"'<>]+)/gi;
+const BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{20,})\b/gi;
+const BASIC_AUTH_PATTERN = /\b(Basic\s+)([A-Za-z0-9+/]{12,}={0,2})(?=$|[\s,;}])/gi;
+const AUTHORIZATION_HEADER_PATTERN = /\b(Authorization\s*:\s*)([A-Za-z][A-Za-z0-9_-]{0,31})(\s+)([^\r\n]+)/gi;
+const QUERY_SECRET_PATTERN = /([?&])([A-Za-z][A-Za-z0-9_.-]{0,80})(=)([^&#\s]+)/gi;
+const DOUBLE_QUOTED_SECRET_ASSIGNMENT_PATTERN = /(^|[\s{[,(;])((?:"|')?[A-Za-z][A-Za-z0-9_.-]{0,80}(?:"|')?\s*)(:|=(?!=))\s*"((?:\\.|[^"\\\r\n])*)"/gim;
+const SINGLE_QUOTED_SECRET_ASSIGNMENT_PATTERN = /(^|[\s{[,(;])((?:"|')?[A-Za-z][A-Za-z0-9_.-]{0,80}(?:"|')?\s*)(:|=(?!=))\s*'((?:\\.|[^'\\\r\n])*)'/gim;
+const SECRET_ASSIGNMENT_PATTERN = /(^|[\s{[,(;])((?:"|')?[A-Za-z][A-Za-z0-9_.-]{0,80}(?:"|')?\s*)(:|=(?!=))\s*([^"'\s,;}]+)/gim;
+const WHITESPACE_SECRET_ASSIGNMENT_PATTERN = /(^|[\s{[,(;])((?:"|')?(?:aws_)?secret_access_key(?:"|')?\s+)(["']?)([A-Za-z0-9/+=]{20,})/gim;
+
+const SENSITIVE_KEY_TERMS = [
+  "api_key",
+  "token",
+  "password",
+  "passwd",
+  "pwd",
+  "secret",
+  "credential",
+  "client_secret",
+  "access_token",
+  "refresh_token",
+  "secret_access_key",
+  "passphrase",
+  "private_key",
+  "signing_key",
+  "authorization"
+];
+const SENSITIVE_PLURAL_KEYS = new Set([
+  "tokens",
+  "api_keys",
+  "passwords",
+  "secrets",
+  "credentials",
+  "client_secrets",
+  "access_tokens",
+  "refresh_tokens",
+  "session_tokens",
+  "passphrases",
+  "private_keys",
+  "signing_keys",
+  "authorizations"
+]);
+const LOWER_THRESHOLD_PLURAL_KEYS = new Set([
+  "passwords",
+  "secrets",
+  "credentials",
+  "passphrases",
+  "private_keys",
+  "signing_keys"
+]);
+
+function normalizeSecretValue(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/^[`"']|[`"']$/g, "")
+    .replace(/[.;)]+$/g, "");
+}
+
+function patternMatches(pattern, value) {
+  pattern.lastIndex = 0;
+  return pattern.test(value);
+}
+
+function looksLikeKnownSecret(value) {
+  return TOKEN_PATTERNS.some((pattern) => patternMatches(pattern, value))
+    || patternMatches(CONNECTION_URL_PATTERN, value)
+    || patternMatches(BEARER_PATTERN, value);
+}
+
+function normalizeSecretKey(key) {
+  return String(key ?? "")
+    .trim()
+    .replace(/^["']|["']$/g, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+}
+
+function keyLooksSensitive(key) {
+  const normalized = normalizeSecretKey(key);
+  return SENSITIVE_PLURAL_KEYS.has(normalized) || SENSITIVE_KEY_TERMS.some((term) => normalized === term
+    || normalized.endsWith(`_${term}`));
+}
+
+function keyRequiresLowerThreshold(key) {
+  const normalized = normalizeSecretKey(key);
+  return LOWER_THRESHOLD_PLURAL_KEYS.has(normalized)
+    || ["password", "passwd", "pwd", "secret", "credential", "passphrase", "private_key", "signing_key"]
+      .some((term) => normalized === term || normalized.endsWith(`_${term}`));
+}
+
+function valueLooksPlaceholder(value) {
+  const clean = normalizeSecretValue(value);
+  if (!clean) return true;
+  if (/^(?:null|undefined|none|false|true|0|""|'')$/i.test(clean)) return true;
+  if (/^<[^>\n]{1,80}>$/.test(clean)) return true;
+  if (/^\[REDACTED_SECRET\]$/i.test(clean)) return true;
+  if (/^(?:not-set|unset|placeholder|example|changeme|change-me|redacted|xxx|\*{3,})$/i.test(clean)) return true;
+  if (/^your[-_][a-z0-9][a-z0-9_-]*$/i.test(clean)) return true;
+  return false;
+}
+
+function valueLooksSensitive(key, value) {
+  const clean = normalizeSecretValue(value);
+  if (!clean || valueLooksPlaceholder(clean)) return false;
+  if (looksLikeKnownSecret(clean)) return true;
+  if (keyRequiresLowerThreshold(key)) return clean.length >= 8;
+  return keyLooksSensitive(key) && clean.length >= 12;
+}
+
+export function redactSensitiveText(input) {
+  if (typeof input !== "string") return { text: "", redacted: false };
+  let text = input;
+
+  text = text.replace(CONNECTION_URL_PATTERN, (_match, prefix, _password, suffix) => `${prefix}${REDACTION}${suffix}`);
+  text = text.replace(BEARER_PATTERN, (_match, prefix) => `${prefix}${REDACTION}`);
+  text = text.replace(BASIC_AUTH_PATTERN, (_match, prefix) => `${prefix}${REDACTION}`);
+  text = text.replace(AUTHORIZATION_HEADER_PATTERN, (match, prefix, scheme, spacing, value) => {
+    if (!valueLooksSensitive("authorization", value)) return match;
+    return `${prefix}${scheme}${spacing}${REDACTION}`;
+  });
+
+  for (const pattern of TOKEN_PATTERNS) text = text.replace(pattern, REDACTION);
+
+  text = text.replace(QUERY_SECRET_PATTERN, (match, prefix, key, separator, value) => {
+    if (!keyLooksSensitive(key) || !valueLooksSensitive(key, value)) return match;
+    return `${prefix}${key}${separator}${REDACTION}`;
+  });
+
+  text = text.replace(DOUBLE_QUOTED_SECRET_ASSIGNMENT_PATTERN, (match, prefix, key, separator, value) => {
+    if (!keyLooksSensitive(key) || !valueLooksSensitive(key, value)) return match;
+    return `${prefix}${key}${separator} "${REDACTION}"`;
+  });
+
+  text = text.replace(SINGLE_QUOTED_SECRET_ASSIGNMENT_PATTERN, (match, prefix, key, separator, value) => {
+    if (!keyLooksSensitive(key) || !valueLooksSensitive(key, value)) return match;
+    return `${prefix}${key}${separator} '${REDACTION}'`;
+  });
+
+  text = text.replace(SECRET_ASSIGNMENT_PATTERN, (match, prefix, key, separator, value) => {
+    if (!keyLooksSensitive(key) || !valueLooksSensitive(key, value)) return match;
+    return `${prefix}${key}${separator} ${REDACTION}`;
+  });
+
+  text = text.replace(WHITESPACE_SECRET_ASSIGNMENT_PATTERN, (match, prefix, key, quote, value) => {
+    if (!valueLooksSensitive(key, value)) return match;
+    return `${prefix}${key}${quote}${REDACTION}`;
+  });
+
+  return { text, redacted: text !== input };
+}
+
+export function containsSensitiveText(input) {
+  return typeof input === "string" && redactSensitiveText(input).redacted;
+}
+
+function redactStorageValue(value, key) {
+  if (typeof value === "string") {
+    const redacted = redactSensitiveText(value);
+    if (redacted.redacted) return redacted.text;
+    return key && keyLooksSensitive(key) && valueLooksSensitive(key, value) ? REDACTION : value;
+  }
+  if (Array.isArray(value)) return value.map((item) => redactStorageValue(item, key));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([childKey, item]) => [childKey, redactStorageValue(item, childKey)])
+  );
+}
+
+export function redactForStorage(value) {
+  return redactStorageValue(value, undefined);
+}

package/packages/piagent-core/skills/piagent-ops/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: piagent-ops
+description: Piagent operating policy for Pi tasks across projects.
+---
+
+# Piagent Ops Skill
+
+Use this skill for every implementation, review, planning, MCP, or tooling task in a project using Pi Agent Platform.
+
+## Mandatory steps
+
+1. Load active project profile with `piagent_context`.
+2. Read required context before planning or editing; use `piagent_context_budget` for large files.
+3. Start source-changing work with `piagent_task_start`.
+4. Respect `protectedPaths`.
+5. Check complex/high-impact shell with `piagent_exec_policy_check`.
+6. Check non-piagent MCP/app tools with `piagent_tool_policy_check`.
+7. Use MCP only when capability is declared.
+8. Prefer small diffs with explicit verification.
+9. Run the exact command from `task.verifyCommands` for passing evidence; ad-hoc commands are advisory only.
+10. Record context, verify, and trace with `piagent_context_record`, `piagent_verify_record`, and `piagent_trace_record`.
+11. Before DONE, call `piagent_task_gate_check`.
+
+## Risk gates
+
+Stop for human confirmation when task touches:
+
+- auth
+- payments
+- data migration
+- external provider setup
+- deploy/release
+- destructive filesystem operation
+- broad refactor across unrelated modules
+
+## Final response
+
+Always include:
+
+- what changed
+- where
+- exact verification result
+- task gate result
+- what remains manual

package/packages/piagent-core/skills/piagent-source-cache/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: piagent-source-cache
+description: Cache and inspect user-provided external Git repositories.
+---
+
+# Piagent Source Cache
+
+Use this skill when the user provides a GitHub/GitLab/Bitbucket repository as source context for a task.
+
+## Goal
+
+Keep external source repositories:
+
+- stable: predictable cache path;
+- fresh: throttled fetch;
+- cheap: no repeated clone;
+- safe: never edit the shared cache directly.
+
+## Workflow
+
+1. Prefer the runtime tool if available:
+
+   ```text
+   piagent_source_checkout(repoRef="owner/repo")
+   ```
+
+2. If the runtime tool is unavailable, resolve the repo into a local checkout from a platform clone:
+
+   ```bash
+   PIAGENT_PLATFORM_HOME=/path/to/piagent-platform
+   bash "$PIAGENT_PLATFORM_HOME/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh" <repo-ref> --path-only
+   ```
+
+3. Use the printed path for targeted `rg`, `sed`, and file reads.
+4. Read only files relevant to the user request.
+5. If edits are needed, create a separate project/worktree; do not edit the cache.
+6. Cite the source URL in reports when needed.
+
+## Supported refs
+
+- `owner/repo`
+- `github.com/owner/repo`
+- `https://github.com/owner/repo`
+- `git@github.com:owner/repo.git`
+
+## Cache location
+
+Default:
+
+```text
+${XDG_CACHE_HOME:-$HOME/.cache}/piagent-platform/checkouts/<host>/<owner>/<repo>
+```
+
+Override:
+
+```bash
+PIAGENT_PLATFORM_HOME=/path/to/piagent-platform
+PIAGENT_CHECKOUT_CACHE=/path/to/cache bash "$PIAGENT_PLATFORM_HOME/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh" owner/repo --path-only
+```

package/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <repo-ref> [--path-only] [--force-update]"
+}
+
+if [[ $# -lt 1 ]]; then
+  usage
+  exit 2
+fi
+
+REPO_REF="$1"
+shift
+
+PATH_ONLY=false
+FORCE_UPDATE=false
+for arg in "$@"; do
+  case "$arg" in
+    --path-only)
+      PATH_ONLY=true
+      ;;
+    --force-update)
+      FORCE_UPDATE=true
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $arg" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+parse_repo_ref() {
+  local ref="$1"
+  local host=""
+  local rest=""
+
+  case "$ref" in
+    http://*|https://*)
+      local no_proto="${ref#*://}"
+      host="${no_proto%%/*}"
+      rest="${no_proto#*/}"
+      ;;
+    git@*:*)
+      local no_user="${ref#git@}"
+      host="${no_user%%:*}"
+      rest="${no_user#*:}"
+      ;;
+    *.*/*/*)
+      host="${ref%%/*}"
+      rest="${ref#*/}"
+      ;;
+    */*)
+      host="github.com"
+      rest="$ref"
+      ;;
+    *)
+      echo "Unsupported repository reference: $ref" >&2
+      return 1
+      ;;
+  esac
+
+  rest="${rest%.git}"
+  IFS="/" read -r owner repo _extra <<< "$rest"
+
+  if [[ -z "${host:-}" || -z "${owner:-}" || -z "${repo:-}" ]]; then
+    echo "Could not parse repository reference: $ref" >&2
+    return 1
+  fi
+
+  if [[ ! "$host" =~ ^[A-Za-z0-9._-]+$ || ! "$owner" =~ ^[A-Za-z0-9._-]+$ || ! "$repo" =~ ^[A-Za-z0-9._-]+$ ]]; then
+    echo "Repository reference contains unsupported characters: $ref" >&2
+    return 1
+  fi
+
+  printf '%s\t%s\t%s\n' "$host" "$owner" "$repo"
+}
+
+IFS=$'\t' read -r HOST OWNER REPO <<< "$(parse_repo_ref "$REPO_REF")"
+
+if [[ -n "${PIAGENT_CHECKOUT_CACHE:-}" ]]; then
+  CACHE_ROOT="$PIAGENT_CHECKOUT_CACHE"
+elif [[ -n "${XDG_CACHE_HOME:-}" ]]; then
+  CACHE_ROOT="$XDG_CACHE_HOME/piagent-platform/checkouts"
+elif [[ -n "${HOME:-}" ]]; then
+  CACHE_ROOT="$HOME/.cache/piagent-platform/checkouts"
+else
+  echo "HOME or PIAGENT_CHECKOUT_CACHE is required" >&2
+  exit 1
+fi
+
+TARGET="$CACHE_ROOT/$HOST/$OWNER/$REPO"
+STAMP_FILE="$TARGET/.piagent-last-fetch"
+FETCH_INTERVAL_SECONDS="${PIAGENT_CHECKOUT_FETCH_INTERVAL_SECONDS:-300}"
+CLONE_URL="https://$HOST/$OWNER/$REPO.git"
+
+if [[ ! -d "$TARGET/.git" ]]; then
+  mkdir -p "$(dirname "$TARGET")"
+  git clone --filter=blob:none -- "$CLONE_URL" "$TARGET" >/dev/null
+  date +%s > "$STAMP_FILE"
+else
+  NOW_SECONDS="$(date +%s)"
+  LAST_FETCH_SECONDS=0
+  if [[ -f "$STAMP_FILE" ]]; then
+    LAST_FETCH_SECONDS="$(tr -cd '0-9' < "$STAMP_FILE" || true)"
+    LAST_FETCH_SECONDS="${LAST_FETCH_SECONDS:-0}"
+  fi
+
+  SHOULD_FETCH=false
+  if [[ "$FORCE_UPDATE" == true ]]; then
+    SHOULD_FETCH=true
+  elif (( NOW_SECONDS - LAST_FETCH_SECONDS >= FETCH_INTERVAL_SECONDS )); then
+    SHOULD_FETCH=true
+  fi
+
+  if [[ "$SHOULD_FETCH" == true ]]; then
+    CLEAN_WORKTREE=false
+    if git -C "$TARGET" diff --quiet --ignore-submodules -- && git -C "$TARGET" diff --cached --quiet --ignore-submodules --; then
+      CLEAN_WORKTREE=true
+    fi
+
+    git -C "$TARGET" fetch --filter=blob:none --prune origin >/dev/null
+
+    if [[ "$CLEAN_WORKTREE" == true ]] && git -C "$TARGET" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+      git -C "$TARGET" merge --ff-only '@{u}' >/dev/null || true
+    fi
+
+    date +%s > "$STAMP_FILE"
+  fi
+fi
+
+if [[ "$PATH_ONLY" == true ]]; then
+  printf '%s\n' "$TARGET"
+else
+  echo "Source cache ready:"
+  echo "  ref: $REPO_REF"
+  echo "  url: $CLONE_URL"
+  echo "  path: $TARGET"
+fi

package/packages/piagent-core/subagents/piagent-oracle.md

@@ -0,0 +1,29 @@
+---
+name: piagent-oracle
+description: Piagent second-opinion advisor for risky plans and architecture decisions
+tools: read, grep, find, ls
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+defaultProgress: true
+acceptance: {"level":"attested"}
+acceptanceRole: read-only
+---
+
+You are `piagent-oracle`, a second-opinion subagent.
+
+Your job is to challenge assumptions before implementation. Do not edit files. Focus on risks, missed constraints, simpler alternatives, and verification strategy.
+
+Return a concise recommendation:
+
+## Oracle Review
+- Best path:
+- Assumptions to challenge:
+- Hidden risks:
+- Simpler alternative:
+- Required verification:
+- Human gate needed:
+- Suggested parent prompt for execution:
+

package/packages/piagent-core/subagents/piagent-planner.md

@@ -0,0 +1,46 @@
+---
+name: piagent-planner
+description: Piagent planner that turns scoped context into an implementation plan with verification gates
+tools: read, grep, find, ls
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+defaultReads: context.md
+defaultProgress: true
+acceptance: {"level":"attested"}
+acceptanceRole: read-only
+---
+
+You are `piagent-planner`, a planning subagent for Pi Agent Platform projects.
+
+Your job is to produce a concrete implementation plan, not to edit files.
+
+Required behavior:
+- Follow project profile, protected paths, required context, memory policy, and verification rules.
+- Apply the current solo-first orchestration policy: parent owns decisions; subagents are bounded helpers, not a default swarm.
+- Use Field Guide/memory only as advisory context and verify durable claims against repository files.
+- Classify risk before proposing source changes.
+- Split work into small stories with non-overlapping write sets when parallel execution is useful.
+- Prefer one writer for a write set. Parallel writers must use worktree isolation.
+- Recommend model roles only as guidance: strongest available model for planning/risk, fastest reliable model for bounded workers, decorrelated model/thinking for review when quality matters.
+- Include exact verification commands and acceptance evidence.
+- If a human gate is required, state it explicitly.
+
+Final output:
+
+## Implementation Plan
+- Goal:
+- Current evidence:
+- Risk lane:
+- Write set:
+- Read-only/protected areas:
+- Task tree/workPlan:
+- Review lenses:
+- Steps:
+- Verification:
+- Suggested subagents:
+- Model-role guidance:
+- Human gates:
+- Open questions:

package/packages/piagent-core/subagents/piagent-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: piagent-reviewer
+description: Piagent reviewer for implementation diff, policy, tests, and scope drift
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+defaultReads: plan.md, progress.md
+defaultProgress: true
+acceptance: {"level":"attested"}
+acceptanceRole: read-only
+maxSubagentDepth: 0
+---
+
+You are `piagent-reviewer`, a disciplined review subagent for Pi Agent Platform projects.
+
+Your job is to review evidence, not to invent issues. Make small corrective edits only when the parent explicitly asks for autofix.
+
+Use explicit review lenses from the parent task when provided. If no lenses are provided, cover correctness, tests/verification, and scope drift first; add security/release/package only when relevant to the change.
+
+Review:
+- task/plan alignment;
+- protected path violations;
+- implementation correctness;
+- tests/verification evidence;
+- security/data-migration/external-provider gates;
+- unnecessary complexity and scope drift.
+
+Rules:
+- Cite exact files and line numbers when possible.
+- Do not run destructive commands.
+- Treat Field Guide/memory as advisory, not as proof.
+- If review-only conflicts with progress-writing or artifact-writing instructions, review-only wins.
+- If a blocker needs a decision, use `contact_supervisor` with `reason: "need_decision"`.
+- Do not spawn other subagents.
+
+Final output:
+
+## Review
+- Lenses covered:
+- Correct:
+- Blockers:
+- Important findings:
+- Notes:
+- Verification observed:
+- Recommended fixes:

package/packages/piagent-core/subagents/piagent-scout.md

@@ -0,0 +1,37 @@
+---
+name: piagent-scout
+description: Piagent read-only scout for bounded repo mapping before planning or implementation
+tools: read, grep, find, ls
+thinking: low
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+defaultProgress: true
+acceptance: {"level":"attested"}
+acceptanceRole: read-only
+---
+
+You are `piagent-scout`, a read-only reconnaissance subagent for Pi Agent Platform projects.
+
+Your job is to map only the code/context needed for the delegated task. Do not edit files. Do not run mutation commands. Do not infer product decisions.
+
+Required behavior:
+- Follow project `AGENTS.md`, `.pi/piagent-profile.json`, `.pi/project-context.md`, and protected-path rules when they are present.
+- Prefer `grep`, `find`, `ls`, and targeted `read`.
+- Return exact file paths and the smallest useful code/context slices.
+- If backend or another protected area is read-only, report gaps instead of changing it.
+- If the task is unclear, list the minimum clarification questions.
+
+Final output:
+
+## Scout Summary
+- Scope inspected:
+- Files that matter:
+- Entry points:
+- Data/control flow:
+- Likely change targets:
+- Protected/read-only areas:
+- Risks or unknowns:
+- Recommended next subagent/task:
+

package/packages/piagent-core/subagents/piagent-worker.md

@@ -0,0 +1,44 @@
+---
+name: piagent-worker
+description: Piagent implementation worker for bounded approved tasks
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+defaultReads: context.md, plan.md
+defaultProgress: true
+acceptance: {"level":"checked"}
+acceptanceRole: writer
+maxSubagentDepth: 0
+---
+
+You are `piagent-worker`, a single-writer implementation subagent for Pi Agent Platform projects.
+
+Your job is to implement a bounded, approved task. The parent session and user remain the decision authority.
+
+Required behavior:
+- Read supplied context/plan first.
+- Follow `AGENTS.md`, `.pi/piagent-profile.json`, `.pi/project-context.md`, protected paths, and verification rules.
+- Stay inside the assigned workPlan step/write set; do not re-plan broader scope unless you contact the supervisor.
+- Treat Field Guide/memory as advisory and verify against current files before relying on it.
+- Make the smallest correct source changes.
+- Do not edit protected/read-only paths unless explicitly delegated by the user.
+- Use `bash` for inspection and verification only.
+- If a required decision is not approved, use `contact_supervisor` with `reason: "need_decision"` and wait.
+- Do not spawn other subagents.
+- Remain the only writer for the delegated write set unless the supervisor explicitly approves worktree-isolated parallel writers.
+- Do not claim success if no edits were made for an implementation task.
+
+Final output:
+
+Implemented: <what changed>
+Changed files:
+- <path>
+Validation:
+- <command/result or N/A with reason>
+Risks/questions:
+- <remaining risk or none>
+Recommended next step:
+- <review/test/ship/etc>