feat(M3): Shared-source generator for agent variants

docs/PI.md

@@ -22,15 +22,18 @@ Related docs:
 
 ### Source Of Truth
 
-Author Pi variants under:
+Edit the **canonical sources** under:
 
-- `skills/atlassian/pi/`
-- `skills/create-plan/pi/`
-- `skills/do-task/pi/`
-- `skills/implement-plan/pi/`
-- `skills/web-automation/pi/`
+- `skills/atlassian/_source/pi/SKILL.md`
+- `skills/create-plan/_source/pi/` (SKILL.md + templates)
+- `skills/do-task/_source/pi/` (SKILL.md + templates)
+- `skills/implement-plan/_source/pi/SKILL.md`
+- `skills/web-automation/_source/pi/SKILL.md`
 
-These are the directories to edit by hand.
+After editing a canonical source, run `pnpm run sync:pi` to regenerate all
+agent-variant directories including `skills/<family>/pi/` and the package mirrors.
+Do not edit the generated `skills/<family>/pi/` directories directly — they are
+overwritten by the generator.
 
 ### Package Mirror
 
@@ -42,7 +45,9 @@ The package exposes:
 - `pi-package/skills/implement-plan/`
 - `pi-package/skills/web-automation/`
 
-Those directories are generated from the source variants by [`scripts/sync-pi-package-skills.sh`](../scripts/sync-pi-package-skills.sh).
+Those directories are generated from the canonical sources by
+[`scripts/generate-skills.mjs`](../scripts/generate-skills.mjs)
+(run via `pnpm run sync:pi`).
 
 ### Shared Setup Docs
 
@@ -106,7 +111,7 @@ The package surface intentionally ships:
 - `docs/PI*.md`
 - `scripts/install-pi-package.sh`
 - `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
-- `scripts/sync-pi-package-skills.sh`
+- `scripts/generate-skills.mjs`
 - `scripts/verify-pi-resources.sh`
 - `scripts/verify-pi-workflows.sh`
 - `scripts/verify-reviewer-support.sh`
@@ -130,7 +135,7 @@ Global installs use `~/.pi/agent/skills/<skill>/` instead of `.pi/skills/<skill>
 When a source Pi variant changes:
 
 ```bash
-./scripts/sync-pi-package-skills.sh
+pnpm run sync:pi
 npm run verify:pi
 npm run verify:reviewers
 npm pack --dry-run --json