pi-crew 0.1.49 → 0.2.0

package/skills/ownership-session-security/SKILL.md

@@ -1,41 +1,41 @@
----
-name: ownership-session-security
-description: Session ownership and authorization workflow. Use when implementing cancel, respond, steer, run ownership, cwd overrides, imported runs, or cross-session actions.
----
-
-# ownership-session-security
-
-Use this skill for cross-session safety and trust-boundary work.
-
-## Source patterns distilled
-
-- Pi session IDs: `ctx.sessionManager.getSessionId()` from Pi core `ExtensionContext`
-- pi-crew ownership: `TeamRunManifest.ownerSessionId`, `src/extension/team-tool/run.ts`, `cancel.ts`, `respond.ts`
-- Path safety: `src/utils/safe-paths.ts`, `src/state/state-store.ts`, `src/state/mailbox.ts`
-- Destructive actions: `src/extension/team-tool/lifecycle-actions.ts`, `src/worktree/cleanup.ts`
-
-## Rules
-
-- Propagate the active Pi session ID into `TeamContext` for every production tool/command path.
-- New runs should record `ownerSessionId` when available.
-- For owned runs, cross-session actions that mutate state must be rejected unless explicit force/admin semantics are designed and tested.
-- Legacy runs without `ownerSessionId` may remain permissive for backward compatibility, but document this behavior.
-- User/LLM-controlled path fields (`cwd`, import paths, artifact paths, task IDs) must be normalized and contained under an allowed base.
-- Use `resolveContainedPath`, `resolveRealContainedPath`, `assertSafePathId`, and symlink checks rather than ad-hoc `startsWith` checks.
-- Destructive management actions must require `confirm: true`; referenced resource deletes must require `force: true` where applicable.
-
-## Anti-patterns
-
-- Assuming `ctx.sessionId` exists directly on Pi context.
-- Letting `cwd: ../other-project` move run state into another project.
-- Letting `respond`/`cancel` mutate a foreign owned run.
-- Trusting task IDs, run IDs, or artifact paths from tool params without validation.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/cancel-ownership.test.ts test/unit/respond-tool.test.ts test/unit/cwd-override-security.test.ts test/unit/api-artifact-security.test.ts
-npm test
-```
+---
+name: ownership-session-security
+description: Session ownership and authorization workflow. Use when implementing cancel, respond, steer, run ownership, cwd overrides, imported runs, or cross-session actions.
+---
+
+# ownership-session-security
+
+Use this skill for cross-session safety and trust-boundary work.
+
+## Source patterns distilled
+
+- Pi session IDs: `ctx.sessionManager.getSessionId()` from Pi core `ExtensionContext`
+- pi-crew ownership: `TeamRunManifest.ownerSessionId`, `src/extension/team-tool/run.ts`, `cancel.ts`, `respond.ts`
+- Path safety: `src/utils/safe-paths.ts`, `src/state/state-store.ts`, `src/state/mailbox.ts`
+- Destructive actions: `src/extension/team-tool/lifecycle-actions.ts`, `src/worktree/cleanup.ts`
+
+## Rules
+
+- Propagate the active Pi session ID into `TeamContext` for every production tool/command path.
+- New runs should record `ownerSessionId` when available.
+- For owned runs, cross-session actions that mutate state must be rejected unless explicit force/admin semantics are designed and tested.
+- Legacy runs without `ownerSessionId` may remain permissive for backward compatibility, but document this behavior.
+- User/LLM-controlled path fields (`cwd`, import paths, artifact paths, task IDs) must be normalized and contained under an allowed base.
+- Use `resolveContainedPath`, `resolveRealContainedPath`, `assertSafePathId`, and symlink checks rather than ad-hoc `startsWith` checks.
+- Destructive management actions must require `confirm: true`; referenced resource deletes must require `force: true` where applicable.
+
+## Anti-patterns
+
+- Assuming `ctx.sessionId` exists directly on Pi context.
+- Letting `cwd: ../other-project` move run state into another project.
+- Letting `respond`/`cancel` mutate a foreign owned run.
+- Trusting task IDs, run IDs, or artifact paths from tool params without validation.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/cancel-ownership.test.ts test/unit/respond-tool.test.ts test/unit/cwd-override-security.test.ts test/unit/api-artifact-security.test.ts
+npm test
+```

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

@@ -1,39 +1,39 @@
----
-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.
----
-
-# pi-extension-lifecycle
-
-Use this skill when working on Pi extension registration or lifecycle behavior.
-
-## Source patterns distilled
-
-- Pi core: `source/pi-mono/packages/coding-agent/src/core/extensions/types.ts`, `loader.ts`, `runner.ts`
-- Pi examples: `source/pi-mono/packages/coding-agent/examples/extensions/`
-- pi-crew extension entry: `src/extension/register.ts`, `src/extension/registration/*.ts`
-
-## Rules
-
-- Register tools, commands, shortcuts, widgets, providers, and event handlers from the extension factory or lifecycle callbacks.
-- Tool definitions should use a TypeBox schema and an `execute(toolCallId, params, signal, onUpdate, ctx)` handler.
-- Use fresh `ExtensionContext`/`ExtensionCommandContext` after session replacement (`newSession`, `fork`, `switchSession`, `reload`). Do not retain old context references for later work.
-- For session-scoped work, derive session identity from `ctx.sessionManager.getSessionId()` and pass it into pi-crew `TeamContext`.
-- Prefer small registration modules under `src/extension/registration/`; keep `index.ts` minimal.
-- 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.
-
-## Anti-patterns
-
-- Do not use stale context objects after session switch.
-- Do not register duplicate tool/command names and assume override behavior.
-- Do not perform blocking filesystem or network work inside extension render callbacks.
-- Do not add hardcoded global keybindings without config or collision review.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-npm test
-```
+---
+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.
+---
+
+# pi-extension-lifecycle
+
+Use this skill when working on Pi extension registration or lifecycle behavior.
+
+## Source patterns distilled
+
+- Pi core: `source/pi-mono/packages/coding-agent/src/core/extensions/types.ts`, `loader.ts`, `runner.ts`
+- Pi examples: `source/pi-mono/packages/coding-agent/examples/extensions/`
+- pi-crew extension entry: `src/extension/register.ts`, `src/extension/registration/*.ts`
+
+## Rules
+
+- Register tools, commands, shortcuts, widgets, providers, and event handlers from the extension factory or lifecycle callbacks.
+- Tool definitions should use a TypeBox schema and an `execute(toolCallId, params, signal, onUpdate, ctx)` handler.
+- Use fresh `ExtensionContext`/`ExtensionCommandContext` after session replacement (`newSession`, `fork`, `switchSession`, `reload`). Do not retain old context references for later work.
+- For session-scoped work, derive session identity from `ctx.sessionManager.getSessionId()` and pass it into pi-crew `TeamContext`.
+- Prefer small registration modules under `src/extension/registration/`; keep `index.ts` minimal.
+- 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.
+
+## Anti-patterns
+
+- Do not use stale context objects after session switch.
+- Do not register duplicate tool/command names and assume override behavior.
+- Do not perform blocking filesystem or network work inside extension render callbacks.
+- Do not add hardcoded global keybindings without config or collision review.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+npm test
+```

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

@@ -1,63 +1,63 @@
----
-name: requirements-to-task-packet
-description: Use when a goal, issue, roadmap item, review finding, or user request must become actionable worker tasks.
----
-
-# 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.
-
-Distilled from detailed reads of clarification, spec-to-implementation, subagent-driven development, and skill-authoring patterns.
-
-## Clarify or Proceed
-
-Ask before implementation when ambiguity affects:
-
-- security boundary, permissions, ownership, or secret handling;
-- destructive operations, migrations, publishing, or public API behavior;
-- architecture or data model;
-- acceptance criteria or rollback expectations.
-
-Proceed with explicit assumptions when ambiguity is local, reversible, and testable.
-
-## Task Packet Template
-
-```text
-Objective:
-Scope/paths:
-Allowed edits:
-Forbidden edits/non-goals:
-Inputs/dependencies:
-Relevant context/artifacts:
-Assumptions:
-Risks:
-Acceptance criteria:
-Verification commands:
-Expected output artifacts:
-Escalation conditions:
-```
-
-## Subagent Context Rules
-
-- Give each worker fresh, curated context; do not rely on hidden parent history.
-- Include exact upstream artifact paths and summaries when needed.
-- Keep implementation tasks independent or explicitly sequenced.
-- Require workers to report one of: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED.
-- For BLOCKED/NEEDS_CONTEXT, change context/model/scope before retrying.
-
-## Acceptance Criteria
-
-Use observable checks:
-
-- command output, state transition, UI/status text, artifact contents;
-- regression tests or named test files;
-- security properties such as containment/ownership/no secrets;
-- compatibility requirements such as Windows paths or Pi CLI flags;
-- rollback notes.
-
-## Anti-patterns
-
-- Broad “fix everything” prompts.
-- Buried assumptions.
-- Expanding scope because context remains.
-- Treating tests as proof when the requirement was never asserted.
+---
+name: requirements-to-task-packet
+description: Use when a goal, issue, roadmap item, review finding, or user request must become actionable worker tasks.
+---
+
+# 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.
+
+Distilled from detailed reads of clarification, spec-to-implementation, subagent-driven development, and skill-authoring patterns.
+
+## Clarify or Proceed
+
+Ask before implementation when ambiguity affects:
+
+- security boundary, permissions, ownership, or secret handling;
+- destructive operations, migrations, publishing, or public API behavior;
+- architecture or data model;
+- acceptance criteria or rollback expectations.
+
+Proceed with explicit assumptions when ambiguity is local, reversible, and testable.
+
+## Task Packet Template
+
+```text
+Objective:
+Scope/paths:
+Allowed edits:
+Forbidden edits/non-goals:
+Inputs/dependencies:
+Relevant context/artifacts:
+Assumptions:
+Risks:
+Acceptance criteria:
+Verification commands:
+Expected output artifacts:
+Escalation conditions:
+```
+
+## Subagent Context Rules
+
+- Give each worker fresh, curated context; do not rely on hidden parent history.
+- Include exact upstream artifact paths and summaries when needed.
+- Keep implementation tasks independent or explicitly sequenced.
+- Require workers to report one of: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED.
+- For BLOCKED/NEEDS_CONTEXT, change context/model/scope before retrying.
+
+## Acceptance Criteria
+
+Use observable checks:
+
+- command output, state transition, UI/status text, artifact contents;
+- regression tests or named test files;
+- security properties such as containment/ownership/no secrets;
+- compatibility requirements such as Windows paths or Pi CLI flags;
+- rollback notes.
+
+## Anti-patterns
+
+- 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,41 +1,41 @@
----
-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.
----
-
-# resource-discovery-config
-
-Use this skill for pi-crew resource/config work.
-
-## Source patterns distilled
-
-- Pi resource loader: `source/pi-mono/packages/coding-agent/src/core/resource-loader.ts`, extension `resources_discover` hook
-- pi-crew discovery: `src/agents/discover-agents.ts`, `src/teams/discover-teams.ts`, `src/workflows/discover-workflows.ts`
-- Config: `src/config/config.ts`, `src/schema/config-schema.ts`, `schema.json`, `docs/resource-formats.md`
-
-## Rules
-
-- Respect discovery precedence: project resources should override user/builtin where supported.
-- Keep built-in resource formats stable and documented.
-- Project config (`.pi/pi-crew.json`) must be sanitized: do not allow dangerous user-only settings such as agent override injection if project trust is lower.
-- Resource paths exposed through Pi hooks must point to package-root resources after build; verify `__dirname` resolution carefully.
-- Avoid dynamic inline imports; keep discovery synchronous or async according to call-site expectations.
-- Validate config with schema and provide actionable errors.
-- When adding new config fields, update defaults, schema, docs, tests, and examples together.
-
-## Anti-patterns
-
-- Resolving package skills to `src/skills` instead of package-root `skills` after publishing.
-- Letting project-local config inject arbitrary global agent overrides.
-- Introducing precedence ambiguity between project/user/builtin resources.
-- Changing resource file syntax without migration notes.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/config-schema-validation.test.ts test/unit/config.test.ts test/unit/extension-api-surface.test.ts test/unit/agent-override-skills.test.ts
-npm test
-npm pack --dry-run
-```
+---
+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.
+---
+
+# resource-discovery-config
+
+Use this skill for pi-crew resource/config work.
+
+## Source patterns distilled
+
+- Pi resource loader: `source/pi-mono/packages/coding-agent/src/core/resource-loader.ts`, extension `resources_discover` hook
+- pi-crew discovery: `src/agents/discover-agents.ts`, `src/teams/discover-teams.ts`, `src/workflows/discover-workflows.ts`
+- Config: `src/config/config.ts`, `src/schema/config-schema.ts`, `schema.json`, `docs/resource-formats.md`
+
+## Rules
+
+- Respect discovery precedence: project resources should override user/builtin where supported.
+- Keep built-in resource formats stable and documented.
+- Project config (`.pi/pi-crew.json`) must be sanitized: do not allow dangerous user-only settings such as agent override injection if project trust is lower.
+- Resource paths exposed through Pi hooks must point to package-root resources after build; verify `__dirname` resolution carefully.
+- Avoid dynamic inline imports; keep discovery synchronous or async according to call-site expectations.
+- Validate config with schema and provide actionable errors.
+- When adding new config fields, update defaults, schema, docs, tests, and examples together.
+
+## Anti-patterns
+
+- Resolving package skills to `src/skills` instead of package-root `skills` after publishing.
+- Letting project-local config inject arbitrary global agent overrides.
+- Introducing precedence ambiguity between project/user/builtin resources.
+- Changing resource file syntax without migration notes.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/config-schema-validation.test.ts test/unit/config.test.ts test/unit/extension-api-surface.test.ts test/unit/agent-override-skills.test.ts
+npm test
+npm pack --dry-run
+```

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

@@ -1,44 +1,44 @@
----
-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.
----
-
-# runtime-state-reader
-
-Use this skill when debugging or auditing a pi-crew run.
-
-## Source patterns distilled
-
-- `src/state/types.ts`, `src/state/contracts.ts`, `src/state/state-store.ts`
-- `src/state/event-log.ts`, `src/state/artifact-store.ts`, `src/runtime/crew-agent-records.ts`
-- `src/extension/run-index.ts`, `src/extension/team-tool/status.ts`, `src/extension/team-tool/inspect.ts`
-
-## Rules
-
-- Prefer exported state APIs over direct file parsing: `loadRunManifestById(cwd, runId)`, run index/list helpers, event readers, and agent readers.
-- Treat state as append-mostly/durable. For review and debugging, do not mutate manifests/tasks/events.
-- Validate run IDs and path-derived IDs; never concatenate untrusted path segments outside state helpers.
-- Read events as JSONL; expect partial/corrupt trailing lines in crash scenarios and handle gracefully.
-- Check status contracts before inferring behavior: terminal vs active run/task statuses matter.
-- Agent aggregate records (`agents.json`) and per-agent status files can disagree briefly; prefer the latest loaded run state plus event log for final conclusions.
-- Include exact paths inspected and distinguish direct evidence from inference.
-
-## Common inspection order
-
-1. Load manifest/tasks.
-2. Check run/task statuses and timestamps.
-3. Read recent events.
-4. Read agent records and per-agent output/status if needed.
-5. Inspect artifacts/diagnostics only through contained paths.
-6. Report root cause and smallest safe remediation.
-
-## Verification
-
-For code changes to state readers:
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/run-index.test.ts test/unit/crew-contracts.test.ts test/unit/atomic-write.test.ts
-npm test
-```
+---
+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.
+---
+
+# runtime-state-reader
+
+Use this skill when debugging or auditing a pi-crew run.
+
+## Source patterns distilled
+
+- `src/state/types.ts`, `src/state/contracts.ts`, `src/state/state-store.ts`
+- `src/state/event-log.ts`, `src/state/artifact-store.ts`, `src/runtime/crew-agent-records.ts`
+- `src/extension/run-index.ts`, `src/extension/team-tool/status.ts`, `src/extension/team-tool/inspect.ts`
+
+## Rules
+
+- Prefer exported state APIs over direct file parsing: `loadRunManifestById(cwd, runId)`, run index/list helpers, event readers, and agent readers.
+- Treat state as append-mostly/durable. For review and debugging, do not mutate manifests/tasks/events.
+- Validate run IDs and path-derived IDs; never concatenate untrusted path segments outside state helpers.
+- Read events as JSONL; expect partial/corrupt trailing lines in crash scenarios and handle gracefully.
+- Check status contracts before inferring behavior: terminal vs active run/task statuses matter.
+- Agent aggregate records (`agents.json`) and per-agent status files can disagree briefly; prefer the latest loaded run state plus event log for final conclusions.
+- Include exact paths inspected and distinguish direct evidence from inference.
+
+## Common inspection order
+
+1. Load manifest/tasks.
+2. Check run/task statuses and timestamps.
+3. Read recent events.
+4. Read agent records and per-agent output/status if needed.
+5. Inspect artifacts/diagnostics only through contained paths.
+6. Report root cause and smallest safe remediation.
+
+## Verification
+
+For code changes to state readers:
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/run-index.test.ts test/unit/crew-contracts.test.ts test/unit/atomic-write.test.ts
+npm test
+```

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

@@ -1,45 +1,45 @@
----
-name: secure-agent-orchestration-review
-description: Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution.
----
-
-# 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.
-
-Distilled from detailed reads of security notice, insecure-defaults, sharp-edges, differential-review, guardrail, and skill quality patterns.
-
-## Trust Boundaries
-
-Review:
-
-- parent session ↔ child Pi worker;
-- user prompt ↔ generated task packet;
-- project skills ↔ package skills;
-- global config ↔ project config;
-- artifacts/logs ↔ future prompts/UI;
-- mailbox/respond/steer/cancel ↔ session ownership;
-- external skills/docs ↔ prompt injection/tool poisoning;
-- runtime env/CLI args ↔ provider/model behavior.
-
-## Must-Check Findings
-
-- Unsafe defaults: scaffold mode unexpectedly enabled, dangerous limits, missing depth guards, overbroad tools.
-- Path containment: cwd override escape, symlink traversal, unsafe skill names, absolute path leakage.
-- Prompt injection: untrusted output treated as instruction, skill metadata overtrusted, missing precedence text.
-- Secrets: env/config/log/artifact/diagnostic leakage.
-- Destructive commands: delete/prune/reset/force push without explicit confirmation.
-- Ownership races: authorization checked outside lock, stale task/manifest written after re-read.
-- Supply chain: external skill content imported without review, unknown tool requirements, hidden commands.
-
-## Secure Defaults for pi-crew
-
-- Real execution should be explicit and disable-able, but generated config must not accidentally block normal workflows.
-- Project overrides should be contained to the project root.
-- Missing/invalid config should fall back safely.
-- 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.
-
-## Finding Format
-
-Include severity, path/symbol, scenario, fix, and verification. Separate must-fix security issues from hardening suggestions.
+---
+name: secure-agent-orchestration-review
+description: Use when reviewing delegation, skill loading, tool access, worker prompts, artifacts, runtime config, state, ownership, or subprocess execution.
+---
+
+# 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.
+
+Distilled from detailed reads of security notice, insecure-defaults, sharp-edges, differential-review, guardrail, and skill quality patterns.
+
+## Trust Boundaries
+
+Review:
+
+- parent session ↔ child Pi worker;
+- user prompt ↔ generated task packet;
+- project skills ↔ package skills;
+- global config ↔ project config;
+- artifacts/logs ↔ future prompts/UI;
+- mailbox/respond/steer/cancel ↔ session ownership;
+- external skills/docs ↔ prompt injection/tool poisoning;
+- runtime env/CLI args ↔ provider/model behavior.
+
+## Must-Check Findings
+
+- Unsafe defaults: scaffold mode unexpectedly enabled, dangerous limits, missing depth guards, overbroad tools.
+- Path containment: cwd override escape, symlink traversal, unsafe skill names, absolute path leakage.
+- Prompt injection: untrusted output treated as instruction, skill metadata overtrusted, missing precedence text.
+- Secrets: env/config/log/artifact/diagnostic leakage.
+- Destructive commands: delete/prune/reset/force push without explicit confirmation.
+- Ownership races: authorization checked outside lock, stale task/manifest written after re-read.
+- Supply chain: external skill content imported without review, unknown tool requirements, hidden commands.
+
+## Secure Defaults for pi-crew
+
+- Real execution should be explicit and disable-able, but generated config must not accidentally block normal workflows.
+- Project overrides should be contained to the project root.
+- Missing/invalid config should fall back safely.
+- 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.
+
+## Finding Format
+
+Include severity, path/symbol, scenario, fix, and verification. Separate must-fix security issues from hardening suggestions.

package/skills/state-mutation-locking/SKILL.md

@@ -1,42 +1,42 @@
----
-name: state-mutation-locking
-description: Durable state mutation and locking workflow. Use when changing manifests, tasks, mailbox, claims, events, stale reconciliation, recovery, cancel/respond/resume, or retry logic.
----
-
-# state-mutation-locking
-
-Use this skill before modifying pi-crew run state.
-
-## Source patterns distilled
-
-- `src/state/locks.ts` — run-level sync/async locks
-- `src/state/state-store.ts` — manifest/tasks persistence
-- `src/state/contracts.ts` — allowed status transitions
-- `src/state/mailbox.ts`, `src/state/task-claims.ts`, `src/state/atomic-write.ts`
-- `src/runtime/crash-recovery.ts`, `src/runtime/stale-reconciler.ts`, `src/runtime/team-runner.ts`
-
-## Rules
-
-- Mutations to a run's `manifest.json`, `tasks.json`, mailbox delivery state, claims, or recovery status must be protected by a run lock when concurrent actions are possible.
-- Re-read manifest/tasks inside the lock before making a decision; pre-lock reads are only for locating the run.
-- Persist with atomic write helpers (`atomicWriteJson`, async variants, or state-store helpers). Do not partially write JSON files.
-- Respect status contracts. Do not transition terminal tasks/runs unless the action explicitly supports force semantics.
-- Separate analysis from persistence: pure reconcilers should return intended repaired state; locked callers should persist it.
-- In retry/resume paths, reload fresh task status immediately before execution and skip if the task is no longer retryable/runnable.
-- Include event-log entries for externally visible state changes.
-
-## Anti-patterns
-
-- Reading state, waiting/doing async work, then writing the old copy.
-- Updating `tasks.json` from a reconciler or watcher without a lock.
-- Cancelling/responding to runs owned by another session.
-- Using `fs.writeFileSync` for JSON state outside atomic helpers.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/cancel-ownership.test.ts test/unit/respond-tool.test.ts test/unit/stale-reconciler.test.ts test/unit/api-claim.test.ts
-npm test
-```
+---
+name: state-mutation-locking
+description: Durable state mutation and locking workflow. Use when changing manifests, tasks, mailbox, claims, events, stale reconciliation, recovery, cancel/respond/resume, or retry logic.
+---
+
+# state-mutation-locking
+
+Use this skill before modifying pi-crew run state.
+
+## Source patterns distilled
+
+- `src/state/locks.ts` — run-level sync/async locks
+- `src/state/state-store.ts` — manifest/tasks persistence
+- `src/state/contracts.ts` — allowed status transitions
+- `src/state/mailbox.ts`, `src/state/task-claims.ts`, `src/state/atomic-write.ts`
+- `src/runtime/crash-recovery.ts`, `src/runtime/stale-reconciler.ts`, `src/runtime/team-runner.ts`
+
+## Rules
+
+- Mutations to a run's `manifest.json`, `tasks.json`, mailbox delivery state, claims, or recovery status must be protected by a run lock when concurrent actions are possible.
+- Re-read manifest/tasks inside the lock before making a decision; pre-lock reads are only for locating the run.
+- Persist with atomic write helpers (`atomicWriteJson`, async variants, or state-store helpers). Do not partially write JSON files.
+- Respect status contracts. Do not transition terminal tasks/runs unless the action explicitly supports force semantics.
+- Separate analysis from persistence: pure reconcilers should return intended repaired state; locked callers should persist it.
+- In retry/resume paths, reload fresh task status immediately before execution and skip if the task is no longer retryable/runnable.
+- Include event-log entries for externally visible state changes.
+
+## Anti-patterns
+
+- Reading state, waiting/doing async work, then writing the old copy.
+- Updating `tasks.json` from a reconciler or watcher without a lock.
+- Cancelling/responding to runs owned by another session.
+- Using `fs.writeFileSync` for JSON state outside atomic helpers.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/cancel-ownership.test.ts test/unit/respond-tool.test.ts test/unit/stale-reconciler.test.ts test/unit/api-claim.test.ts
+npm test
+```