feat(development/pi-coding-agent): added instructions on using subagents

13 files changed, 94 insertions, 10 deletions

diff --git a/modules/development/pi-coding-agent/default.nix b/modules/development/pi-coding-agent/default.nix
index 01a83ac..e560a98 100644
--- a/modules/development/pi-coding-agent/default.nix
+++ b/modules/development/pi-coding-agent/default.nix
@@ -109,9 +109,9 @@ in
         context = ./CONTEXT.md;
       };
 
-      extraPackages = with pkgs; [
-        nodejs
-        bun
+      extraPackages = [
+        pkgs.nodejs
+        pkgs.bun
       ];
     };
   };
diff --git a/modules/development/pi-coding-agent/skills/architecture/SKILL.md b/modules/development/pi-coding-agent/skills/architecture/SKILL.md
index 5097418..9b2b53d 100644
--- a/modules/development/pi-coding-agent/skills/architecture/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/architecture/SKILL.md
@@ -7,6 +7,13 @@ description: "Understand module boundaries, dependencies, data flow, public inte
 
 Understand existing boundaries and dependencies before proposing structural changes; useful for large repositories.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a large codebase, you might spawn a **scout** to map module boundaries in the `auth` package, another **scout** to trace data flow in the `payment` pipeline, and a **reviewer** to verify that the proposed interface changes don't break downstream consumers—all running in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Analysis
 
 ### 1. Module Boundaries
@@ -32,4 +39,4 @@ Understand existing boundaries and dependencies before proposing structural chan
 ### 5. Risks
 - Migration complexity
 - Testing implications
-- Rollback feasibility
\ No newline at end of file
+- Rollback feasibility
diff --git a/modules/development/pi-coding-agent/skills/code-review/SKILL.md b/modules/development/pi-coding-agent/skills/code-review/SKILL.md
index 6629d52..bdbacd0 100644
--- a/modules/development/pi-coding-agent/skills/code-review/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/code-review/SKILL.md
@@ -7,6 +7,13 @@ description: "Review diffs for correctness, edge cases, regressions, API compati
 
 Review diffs for correctness, edge cases, regressions, API compatibility, maintainability, and missing tests.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a large pull request, you could assign one **scout** to read the changed files in the `api` layer, another **scout** to inspect the `database` migrations, and a **reviewer** to check each area for correctness, edge cases, and API compatibility—then aggregate their findings into a single review.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Checklist
 
 ### Correctness
@@ -34,4 +41,4 @@ Review diffs for correctness, edge cases, regressions, API compatibility, mainta
 ### Tests
 - [ ] New functionality tested
 - [ ] Edge cases covered
-- [ ] Regression tests added
\ No newline at end of file
+- [ ] Regression tests added
diff --git a/modules/development/pi-coding-agent/skills/debugging/SKILL.md b/modules/development/pi-coding-agent/skills/debugging/SKILL.md
index 05c2de0..6592a84 100644
--- a/modules/development/pi-coding-agent/skills/debugging/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/debugging/SKILL.md
@@ -7,6 +7,13 @@ description: "A systematic workflow; reproduce -> inspect logs/errors -> isolate
 
 A systematic workflow: reproduce -> inspect logs/errors -> isolate cause -> form hypothesis -> test -> fix -> regression test.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When debugging a flaky test, spawn a **scout** to reproduce the issue in a clean environment, another **scout** to analyze the relevant log files, and an **implementer** to apply a targeted fix while a **reviewer** runs the regression suite—all in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Workflow
 
 ### 1. Reproduce
diff --git a/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md b/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md
index 213e848..a36f80f 100644
--- a/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md
@@ -7,6 +7,13 @@ description: "Investigate whether a dependency is actually necessary, check exis
 
 Investigate whether a dependency is actually necessary, check existing versions/conventions, minimize dependency additions, and update lockfiles deliberately.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To evaluate a new dependency, use a **scout** to check if the functionality exists in the standard library, another **scout** to compare versions and licensing of alternatives, and a **reviewer** to verify the lockfile update doesn't introduce transitive conflicts.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Process
 
 ### 1. Necessity
@@ -27,4 +34,4 @@ Investigate whether a dependency is actually necessary, check existing versions/
 ### 4. Update
 - Update lockfiles atomically
 - Test after updates
-- Document breaking changes
\ No newline at end of file
+- Document breaking changes
diff --git a/modules/development/pi-coding-agent/skills/documentation/SKILL.md b/modules/development/pi-coding-agent/skills/documentation/SKILL.md
index 6d6a6e1..d7ad4bf 100644
--- a/modules/development/pi-coding-agent/skills/documentation/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/documentation/SKILL.md
@@ -7,6 +7,13 @@ description: "Generate/update README/API/architecture docs from the actual imple
 
 Generate/update README/API/architecture docs from the actual implementation rather than inventing behavior.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a new feature, assign a **scout** to extract API signatures from the `service` module, another **scout** to gather usage examples from the `cli` package, and an **implementer** to generate the corresponding README and API docs sections simultaneously.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Principles
 
 ### Source of Truth
@@ -22,4 +29,4 @@ Generate/update README/API/architecture docs from the actual implementation rath
 ### Maintenance
 - Update with code changes
 - Delete stale documentation
-- Link to code references
\ No newline at end of file
+- Link to code references
diff --git a/modules/development/pi-coding-agent/skills/git/SKILL.md b/modules/development/pi-coding-agent/skills/git/SKILL.md
index 7331fc5..df60f8f 100644
--- a/modules/development/pi-coding-agent/skills/git/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/git/SKILL.md
@@ -7,6 +7,13 @@ description: "Inspect status/diff/history, preserve user work, create focused co
 
 Inspect status/diff/history, preserve user work, create focused commits when requested, help with merges/rebases/conflicts.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When preparing a complex merge, spawn a **scout** to analyze the commit history of the `feature` branch, another **scout** to inspect the conflicting files in `core`, and a **reviewer** to verify the merged result passes all tests before pushing.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Operations
 
 ### Inspect
diff --git a/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md b/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md
index e8dad8b..0a65471 100644
--- a/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md
@@ -7,6 +7,13 @@ description: "Measure before optimizing, identify likely bottlenecks, make a tar
 
 Measure before optimizing, identify likely bottlenecks, make a targeted change, and verify the effect.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To optimize a slow endpoint, run a **scout** to profile CPU usage in the `handler` function, another **scout** to measure I/O latency in the `storage` layer, and an **implementer** to apply algorithmic improvements while a **reviewer** compares benchmarks against the baseline.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Workflow
 
 ### 1. Measure
@@ -27,4 +34,4 @@ Measure before optimizing, identify likely bottlenecks, make a targeted change,
 ### 4. Verify
 - Re-measure after change
 - Compare to baseline
-- Check for regressions
\ No newline at end of file
+- Check for regressions
diff --git a/modules/development/pi-coding-agent/skills/refactoring/SKILL.md b/modules/development/pi-coding-agent/skills/refactoring/SKILL.md
index f947cff..09f01fa 100644
--- a/modules/development/pi-coding-agent/skills/refactoring/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/refactoring/SKILL.md
@@ -7,6 +7,13 @@ description: "Explicitly preserve behavior while improving structure; identify u
 
 Explicitly preserve behavior while improving structure; identify unnecessary abstraction and avoid scope creep.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When refactoring a legacy module, use a **scout** to identify all call sites of the `legacy::utils` functions, another **scout** to map the test coverage for each, and an **implementer** to inline or replace them incrementally while a **reviewer** ensures behavior is preserved.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Principles
 
 ### Preserve Behavior
diff --git a/modules/development/pi-coding-agent/skills/release/SKILL.md b/modules/development/pi-coding-agent/skills/release/SKILL.md
index 7612eef..a81acfd 100644
--- a/modules/development/pi-coding-agent/skills/release/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/release/SKILL.md
@@ -7,6 +7,13 @@ description: "Build -> test -> inspect artifacts -> changelog/versioning -> pack
 
 Build -> test -> inspect artifacts -> changelog/versioning -> package/release checks.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a multi-platform release, assign a **scout** to build the Linux artifact, another **scout** to build the macOS artifact, a third to run the integration test suite, and a **reviewer** to verify version tags and changelog entries before publishing.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Process
 
 ### 1. Build
diff --git a/modules/development/pi-coding-agent/skills/research/SKILL.md b/modules/development/pi-coding-agent/skills/research/SKILL.md
index 53629ec..c906a1c 100644
--- a/modules/development/pi-coding-agent/skills/research/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/research/SKILL.md
@@ -7,6 +7,13 @@ description: "For unfamiliar APIs or libraries; identify authoritative sources,
 
 For unfamiliar APIs or libraries: identify authoritative sources, compare alternatives, verify version-specific behavior, and separate verified facts from assumptions.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When evaluating a new library, spawn a **scout** to read the official documentation, another **scout** to search for community benchmarks, and a **reviewer** to compare the findings against your project's requirements and version constraints.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Process
 
 ### 1. Identify Sources
diff --git a/modules/development/pi-coding-agent/skills/security-review/SKILL.md b/modules/development/pi-coding-agent/skills/security-review/SKILL.md
index 0b2d307..3f534ab 100644
--- a/modules/development/pi-coding-agent/skills/security-review/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/security-review/SKILL.md
@@ -7,6 +7,13 @@ description: "Look for secrets, injection, unsafe shell execution, auth/authz mi
 
 Look for secrets, injection, unsafe shell execution, auth/authz mistakes, dependency risks, path traversal, SSRF, insecure defaults, etc.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a security audit, run a **scout** to scan for injection vulnerabilities in the input validators, another **scout** to review authentication flows for authz mistakes, and a **reviewer** to check for path traversal and SSRF in file-handling code—all in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Checklist
 
 ### Secrets & Credentials
@@ -47,4 +54,4 @@ Look for secrets, injection, unsafe shell execution, auth/authz mistakes, depend
 ### Insecure Defaults
 - [ ] Secure defaults enabled
 - [ ] Debug endpoints disabled
-- [ ] Proper CORS configuration
\ No newline at end of file
+- [ ] Proper CORS configuration
diff --git a/modules/development/pi-coding-agent/skills/testing/SKILL.md b/modules/development/pi-coding-agent/skills/testing/SKILL.md
index 4b1b6eb..4785fe7 100644
--- a/modules/development/pi-coding-agent/skills/testing/SKILL.md
+++ b/modules/development/pi-coding-agent/skills/testing/SKILL.md
@@ -7,6 +7,13 @@ description: "Figure out the project's existing test strategy, add targeted test
 
 Figure out the project's existing test strategy, add targeted tests, run the smallest useful test set, then broaden validation.
 
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To expand test coverage, assign a **scout** to run the existing unit test suite and report gaps, another **scout** to generate property-based tests for the `parser` module, and an **implementer** to add integration tests for the `api` endpoints while a **reviewer** verifies the new tests pass.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
 ## Process
 
 ### 1. Discover
@@ -32,4 +39,4 @@ Figure out the project's existing test strategy, add targeted tests, run the sma
 ### 5. Report
 - Document what was tested
 - Note any skipped tests
-- Report coverage gaps
\ No newline at end of file
+- Report coverage gaps