pi-crew 0.5.2 → 0.5.6

package/skills/pi-extension-lifecycle/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: pi-extension-lifecycle
-description: Pi extension lifecycle and registration patterns. Use when adding or reviewing extension tools, commands, resources, providers, event handlers, session hooks, or context-sensitive Pi API usage.
----
+description: Pi extension lifecycle and registration patterns.
+triggers:
+  - "add extension"
+  - "register tools"
+  - "session hooks"
+  - "context API"
+  - "extension lifecycle"
 
+---
 # pi-extension-lifecycle
 
 Use this skill when working on Pi extension registration or lifecycle behavior.
@@ -23,6 +29,18 @@ Use this skill when working on Pi extension registration or lifecycle behavior.
 - Clean up intervals, event subscriptions, child processes, and watchers on session switch/shutdown.
 - Wrap optional Pi API hooks in compatibility checks/try-catch when supporting older Pi versions.
 
+## Enforcement — Pi Extension Lifecycle Gate
+
+**Before registering tools or handling session lifecycle, verify:**
+
+- [ ] ExtensionContext/ExtensionCommandContext fresh after session replacement
+- [ ] No stale context references retained after session switch/fork/reload
+- [ ] Cleanup registered for intervals, subscriptions, child processes, watchers
+- [ ] Tool/command names unique (no duplicate registrations)
+- [ ] No blocking filesystem/network work in extension render callbacks
+
+If ANY answer is NO → Stop. Fix lifecycle issues before proceeding.
+
 ## Anti-patterns
 
 - Do not use stale context objects after session switch.

package/skills/post-mortem/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: post-mortem
-description: "Write engineering RCA record after bug is fixed. Use when asking: write post-mortem, RCA, root cause analysis, document this fix, close out this bug. Triggers: post-mortem, postmortem, root cause, RCA, document this fix, write up the cause, close out bug."
+description: "Write engineering RCA record after bug is fixed."
+triggers:
+  - "post-mortem"
+  - "root cause"
+  - "RCA"
+  - "document this fix"
+  - "close out bug"
 ---
-
 # post-mortem
 
 The canonical engineering record of a bug fix. Written after debugging lands a real fix.

package/skills/read-only-explorer/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: read-only-explorer
-description: Read-only exploration and audit workflow. Use for explorer, analyst, reviewer, and source-audit roles that must inspect code without modifying files.
----
+description: "Read-only exploration and audit workflow."
+triggers:
+  - "explore code"
+  - "audit source"
+  - "review code"
+  - "analyze codebase"
+  - "source audit"
 
+---
 # read-only-explorer
 
 Use this skill for explorer, analyst, reviewer, and source-audit roles. These roles must inspect code without modifying it.
@@ -209,6 +215,18 @@ For each step, identify:
 
 Always label uncertainty clearly. Use "may", "might", "could" for inference; "is", "shows", "contains" for evidence.
 
+## Enforcement — Read-Only Explorer Gate
+
+**Before reporting findings, verify:**
+
+- [ ] No files edited, written, or deleted (read-only contract maintained)
+- [ ] Findings include: path, line, evidence, severity, impact, recommendation
+- [ ] Exact files inspected recorded with paths and line numbers
+- [ ] Direct evidence distinguished from inference (cite vs guess)
+- [ ] If implementation needed, recommend (do not modify code)
+
+If ANY answer is NO → Stop. Adhere to read-only contract.
+
 ## Anti-patterns
 
 - **Editing during exploration**: If you need to add logging or print statements, use a separate test script instead of modifying source files.
@@ -218,8 +236,6 @@ Always label uncertainty clearly. Use "may", "might", "could" for inference; "is
 - **Not recording files inspected**: Without exact paths, findings can't be verified.
 - **Inference as fact**: If unsure, mark it as inference.
 
----
-
 ## Source patterns
 
 - `src/runtime/task-runner.ts` — task execution pipeline
@@ -229,8 +245,6 @@ Always label uncertainty clearly. Use "may", "might", "could" for inference; "is
 - `src/extension/team-tool/` — API and tool handling
 - `src/ui/` — widget and TUI rendering
 
----
-
 ## Verification
 
 ```bash

package/skills/requirements-to-task-packet/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: requirements-to-task-packet
-description: Use when a goal, issue, roadmap item, review finding, or user request must become actionable worker tasks.
----
+description: "Use when a goal, issue, roadmap item, review finding, or user request must become actionable worker tasks."
+triggers:
+  - "convert requirements"
+  - "create task packet"
+  - "decompose goal"
+  - "write task"
+  - "spec to implementation"
 
+---
 # requirements-to-task-packet
 
 Core principle: workers need explicit task packets, not inherited ambiguity. Ask only when ambiguity changes architecture, safety, public behavior, or data loss risk; otherwise record assumptions.
@@ -55,9 +61,23 @@ Use observable checks:
 - compatibility requirements such as Windows paths or Pi CLI flags;
 - rollback notes.
 
+## Enforcement — Requirements to Task Packet Gate
+
+**Before dispatching workers, verify task packet has:**
+
+- [ ] Objective clearly stated (goal in one sentence)
+- [ ] Scope and paths defined (what is/isn't in scope)
+- [ ] Allowed vs forbidden edits specified
+- [ ] Inputs/dependencies and expected output artifacts listed
+- [ ] Acceptance criteria are observable (command output, state transition, test)
+- [ ] Verification commands provided
+- [ ] Escalation conditions defined
+
+If ANY answer is NO → Stop. Complete task packet before dispatching.
+
 ## Anti-patterns
 
-- Broad “fix everything” prompts.
+- Broad "fix everything" prompts.
 - Buried assumptions.
 - Expanding scope because context remains.
 - Treating tests as proof when the requirement was never asserted.

package/skills/resource-discovery-config/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: resource-discovery-config
-description: pi-crew resource and configuration discovery workflow. Use when changing agents, teams, workflows, skills, resource hooks, config precedence, or project/user overrides.
----
+description: "pi-crew resource and configuration discovery workflow."
+triggers:
+  - "discover agents"
+  - "find teams"
+  - "config override"
+  - "resource discovery"
+  - "skill loading"
 
+---
 # resource-discovery-config
 
 Use this skill for pi-crew resource/config work.
@@ -23,6 +29,18 @@ Use this skill for pi-crew resource/config work.
 - Validate config with schema and provide actionable errors.
 - When adding new config fields, update defaults, schema, docs, tests, and examples together.
 
+## Enforcement — Resource Discovery Config Gate
+
+**Before adding config or changing resource discovery, verify:**
+
+- [ ] Discovery precedence respected (project > user > builtin)
+- [ ] Config schema validated with actionable errors on invalid input
+- [ ] Dangerous user-only settings blocked in lower-trust contexts
+- [ ] Resource paths resolved correctly (package-root not src/skills after build)
+- [ ] New config fields have defaults, schema, docs, tests, and examples
+
+If ANY answer is NO → Stop. Fix config/discovery issues before proceeding.
+
 ## Anti-patterns
 
 - Resolving package skills to `src/skills` instead of package-root `skills` after publishing.

package/skills/runtime-state-reader/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: runtime-state-reader
-description: Safe read-only navigation of pi-crew run state. Use for inspecting manifests, tasks, events, agents, artifacts, health, and diagnostics without modifying state.
+description: Safe read-only navigation of pi-crew run state.
+triggers:
+  - "inspect manifest"
+  - "read tasks"
+  - "trace events"
+  - "examine state"
+  - "diagnostics"
 ---
-
 # runtime-state-reader
 
 Use this skill when debugging or auditing a pi-crew run.
@@ -32,6 +37,19 @@ Use this skill when debugging or auditing a pi-crew run.
 5. Inspect artifacts/diagnostics only through contained paths.
 6. Report root cause and smallest safe remediation.
 
+## Enforcement — Runtime State Reader Gate
+
+**Before inspecting or reporting on run state, verify:**
+
+- [ ] Using exported state APIs (not direct file parsing where helpers exist)
+- [ ] State treated as append-mostly (no mutations during review/debugging)
+- [ ] runId validated before use (no untrusted path concatenation)
+- [ ] Corrupt JSONL handled gracefully (skip malformed lines)
+- [ ] Terminal vs active statuses distinguished (critical for conclusions)
+- [ ] Exact paths inspected reported with direct evidence vs inference labeled
+
+If ANY answer is NO → Stop. Verify state access method before proceeding.
+
 ## Verification
 
 For code changes to state readers:

package/skills/safe-bash/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: safe-bash
-description: "Safe shell-command workflow. Use when executing shell commands, prefer read-only, avoid destructive actions. Triggers: run this command, execute bash, safe bash, avoid rm, destructive command, shell injection."
----
+description: "Safe shell-command workflow."
+triggers:
+  - "run this command"
+  - "execute bash"
+  - "safe bash"
+  - "destructive command"
+  - "shell injection"
 
+---
 # safe-bash
 
 Use this skill whenever a task may execute shell commands. This skill covers cross-platform shell safety, destructive action confirmation, and Windows-specific patterns.
@@ -268,6 +274,19 @@ else
 fi
 ```
 
+## Enforcement — Safe Bash Gate
+
+**Before executing shell commands, verify:**
+
+- [ ] Command classified as read-only or mutating (report which)
+- [ ] Mutating/destructive commands have explicit confirmation before execution
+- [ ] Paths use platform-safe construction (path.join, not hardcoded forward slashes)
+- [ ] Timeout set for long-running commands (prevent blocking)
+- [ ] Exit codes checked and errors handled appropriately
+- [ ] Secrets not passed in command-line args (use environment variables)
+
+If ANY answer is NO → Stop. Classify and protect before executing.
+
 ## Anti-patterns
 
 - **`rm -rf` without path validation**: Always double-check the path before rm -rf
@@ -277,8 +296,6 @@ fi
 - **Not handling Windows spaces**: Test on Windows before assuming paths work
 - **Background process zombie**: Always handle process exit or store the pid for cleanup
 
----
-
 ## Source patterns
 
 - `src/utils/resolve-shell.ts` — cross-platform shell detection
@@ -286,8 +303,6 @@ fi
 - `src/worktree/worktree-manager.ts` — git commands via execFileSync
 - `src/config/defaults.ts` — platform detection
 
----
-
 ## Verification
 
 ```bash

package/skills/scrutinize/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: scrutinize
-description: "Outsider-perspective review questioning intent before tracing code. Use when asking: should this even exist?, is there a simpler way?, get a second opinion, before deep code review. Triggers: scrutinize this, question this, is there a better way?, simplify this, overkill?, too complex."
----
+description: "Outsider-perspective review questioning intent before tracing code."
+triggers:
+  - "scrutinize this"
+  - "question this"
+  - "is there a better way"
+  - "simplify this"
+  - "too complex"
 
+---
 # Scrutinize
 
 Stand outside the change and ask whether it should exist at all, then verify it actually does what it claims end-to-end.
@@ -58,6 +64,18 @@ Severity:
 
 Close with verdict: **ship / fix-then-ship / rework / reject** — with single biggest reason.
 
+## Enforcement — Scrutinize Gate
+
+**Before reporting scrutiny findings, verify:**
+
+- [ ] Simpler-alternative pass completed (delete, use existing, smaller change, different layer)
+- [ ] Intent stated in one sentence in your own words
+- [ ] Code traced end-to-end (not just diff lines)
+- [ ] Verdict given: ship / fix-then-ship / rework / reject
+- [ ] Every claim cited with specific path/file/line evidence
+
+If ANY answer is NO → Stop. Complete scrutiny requirements before reporting.
+
 ## Rules
 
 - **No rubber-stamps.** "LGTM" is not an output. If nothing found, say what you traced.

package/skills/secure-agent-orchestration-review/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: secure-agent-orchestration-review
-description: Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution.
----
+description: "Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution."
+triggers:
+  - "review delegation"
+  - "check skill security"
+  - "audit prompts"
+  - "security review"
+  - "orchestration audit"
+
 
+---
 # secure-agent-orchestration-review
 
 Core principle: every delegated worker crosses trust boundaries. Safe orchestration requires contained paths, explicit ownership, scoped tools, non-invasive defaults, and prompt-injection resistance.
@@ -40,6 +47,26 @@ Review:
 - Skills should be loaded by safe name and source-labeled without absolute path disclosure.
 - Worker prompts should state instruction precedence and treat artifacts as data.
 
+## Enforcement — Secure Agent Orchestration Review Gate
+
+**Before reporting security findings, verify:**
+
+- [ ] All trust boundaries examined (parent↔child, user↔task packet, project↔package skills, etc.)
+- [ ] Must-check findings covered: unsafe defaults, path containment, prompt injection, secrets, destructive commands, ownership races, supply chain
+- [ ] Finding format complete: severity, path/symbol, scenario, fix, verification
+- [ ] Must-fix security issues separated from hardening suggestions
+- [ ] Verification commands provided for each finding
+
+If ANY answer is NO → Stop. Complete security review before reporting.
+
 ## Finding Format
 
 Include severity, path/symbol, scenario, fix, and verification. Separate must-fix security issues from hardening suggestions.
+
+## Anti-Patterns
+
+- **Don't** skip checking for unsafe defaults in configuration
+- **Don't** trust agent output without verifying path containment
+- **Don't** skip prompt injection checks when processing user input
+- **Don't** skip secrets detection in environment and config files
+- **Don't** skip checking for ownership race conditions in concurrent operations