pi-crew 0.1.45 → 0.1.46

package/docs/research-awesome-agent-skills-distillation.md

@@ -0,0 +1,100 @@
+# Awesome Agent Skills Distillation for pi-crew
+
+Date: 2026-05-05
+Source repo: `source/awesome-agent-skills` at `859172a` after fast-forward pull from `VoltAgent/awesome-agent-skills`.
+
+## Source Character
+
+`awesome-agent-skills` is a curated index/README of external agent skills, not a vendored skill-source tree. pi-crew should not copy external skill text from linked repositories. This distillation uses high-level themes from the index plus selected detailed reads of linked skills, rewritten as pi-crew-native workflows rather than vendored text.
+
+## Detailed Links Read
+
+Accessible raw GitHub links inspected:
+
+- `obra/superpowers`:
+  - `verification-before-completion/SKILL.md` — evidence before claims; fresh command output required.
+  - `systematic-debugging/SKILL.md` — no fixes without root-cause investigation; four-phase debug loop.
+  - `subagent-driven-development/SKILL.md` — fresh subagent context, staged review checkpoints, DONE/NEEDS_CONTEXT/BLOCKED handling.
+  - `requesting-code-review/SKILL.md` — review early/often with explicit base/head context.
+  - `receiving-code-review/SKILL.md` — verify feedback before implementing; push back with technical evidence.
+  - `using-git-worktrees/SKILL.md` — detect existing isolation, prefer native worktree tools, verify clean baseline.
+  - `finishing-a-development-branch/SKILL.md` — verify tests before merge/PR/discard options.
+  - `test-driven-development/SKILL.md` — red/green/refactor; tests must fail for the intended reason.
+  - `writing-skills/SKILL.md` — trigger-only descriptions, progressive skill structure, pressure-test skills.
+
+Blocked/unavailable in this environment:
+
+- `officialskills.sh` pages for Trail of Bits/OpenAI returned HTTP 403 when fetched directly.
+- Some README paths have moved or are directory-based; missing paths were not treated as source of truth.
+
+Relevant source themes:
+
+- Trail of Bits: clarification, audit context, differential review, insecure defaults, sharp edges, static analysis, testing handbook.
+- OpenAI/Sentry/CodeRabbit/Garry Tan: security review, threat modeling, PR/code review, QA, guardrails, release/deploy verification.
+- Obra/NeoLab community skills: subagent-driven development, testing with subagents, worktrees, verification before completion, recursive decomposition, review checkpoints.
+- Context-engineering entries: context degradation, compression, memory systems, tool design, evaluation frameworks.
+- Skill quality standards: specific descriptions, progressive disclosure, no absolute paths, scoped tools.
+- Security notice: skills are curated but not audited; external skill content can contain prompt injection, tool poisoning, malware payloads, or unsafe data handling.
+
+## Added pi-crew Skills
+
+### `requirements-to-task-packet`
+
+Purpose: convert ambiguous work into task packets with assumptions, scope, non-goals, acceptance criteria, verification, and escalation conditions.
+
+Primary roles: `analyst`, `planner`.
+
+### `secure-agent-orchestration-review`
+
+Purpose: security-review workflow for delegation, skill loading, tool access, prompts, artifacts, config, and session/state ownership.
+
+Primary role: `security-reviewer`.
+
+### `multi-perspective-review`
+
+Purpose: structured review protocol separating correctness, security, tests, maintainability, operator experience, and compatibility.
+
+Primary roles: `reviewer`, `critic`.
+
+### `verification-before-done`
+
+Purpose: completion gate requiring targeted checks, typecheck/integration/full test escalation, evidence, artifacts, risks, and rollback notes.
+
+Primary roles: `executor`, `test-engineer`, `verifier`.
+
+### `context-artifact-hygiene`
+
+Purpose: prevent context poisoning, lost-in-middle failures, stale artifacts, absolute-path leakage, and poor handoffs.
+
+Primary roles: `explorer`, `writer`.
+
+### `systematic-debugging`
+
+Purpose: reproduce/trace/hypothesize/fix loop for failing tests, blocked runs, config pollution, provider/runtime errors, and stale state.
+
+Not currently default-mapped to avoid skill-budget bloat; can be requested by `skill: "systematic-debugging"` or added to future debug workflows.
+
+## Default Role Mapping Changes
+
+Updated `src/runtime/skill-instructions.ts` to use the new distilled skills while keeping prompt budgets small:
+
+- `explorer`: `read-only-explorer`, `context-artifact-hygiene`
+- `analyst`: `read-only-explorer`, `requirements-to-task-packet`
+- `planner`: `delegation-patterns`, `requirements-to-task-packet`
+- `critic`: `read-only-explorer`, `multi-perspective-review`
+- `executor`: `state-mutation-locking`, `safe-bash`, `verification-before-done`
+- `reviewer`: `read-only-explorer`, `multi-perspective-review`
+- `security-reviewer`: `secure-agent-orchestration-review`, `ownership-session-security`
+- `test-engineer`: `verification-before-done`, `safe-bash`
+- `verifier`: `verification-before-done`, `runtime-state-reader`
+- `writer`: `context-artifact-hygiene`, `verify-evidence`
+
+## Rationale
+
+The selected skills are generic, pi-crew-native, and immediately useful for team orchestration. Vendor/framework-specific skills from the index were intentionally skipped because pi-crew is a TypeScript Pi extension and should not bake in unrelated platform instructions.
+
+## Follow-up Ideas
+
+- Add workflow-level `skills:` defaults for debug/recovery workflows that include `systematic-debugging`.
+- Add a `skill-supply-chain-audit` skill if pi-crew later imports external skill bundles automatically.
+- Add documentation to README describing `skill` override usage and project `skills/<name>/SKILL.md` overrides.