feat(M3): Shared-source generator for agent variants
This commit is contained in:
Stefano Fiorini
+1
-1
@@ -138,7 +138,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/atlassian
|
||||
cp -R pi-package/skills/atlassian/* .pi/skills/atlassian/
|
||||
cd .pi/skills/atlassian/scripts
|
||||
|
||||
@@ -293,6 +293,59 @@ changes the baseline status of a check.*
|
||||
|
||||
---
|
||||
|
||||
## Post-M3 state
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
M3 resolved all remaining pre-existing `lint` violations (2 ESLint errors and
|
||||
7 shellcheck findings). `verify:generated` is now a real implementation
|
||||
(was a stub in M2).
|
||||
|
||||
### `pnpm run check` aggregate (post-M3)
|
||||
|
||||
```text
|
||||
PASS lint (was FAIL in M1/M2; pre-existing violations fixed in M3)
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
PASS verify:docs
|
||||
PASS verify:generated (was stub in M2; real implementation in M3)
|
||||
```
|
||||
|
||||
Overall exit: **0** — all checks green for the first time.
|
||||
|
||||
### What changed in M3
|
||||
|
||||
- `scripts/generate-skills.mjs` added (generator for all 31 agent-variant roots).
|
||||
- `scripts/verify-generated.mjs` added (drift detector).
|
||||
- Canonical source directories created: `skills/<skill>/_source/`,
|
||||
`skills/web-automation/shared/`.
|
||||
- All 31 generated roots now carry `.generated-manifest.json` and file-type-aware
|
||||
headers.
|
||||
- `package.json` renames: all generated agent-variant packages renamed to
|
||||
`@ai-coding-skills/<skill>-<agent>` with `"private": true`.
|
||||
- `pnpm-workspace.yaml` updated: M1 negative-glob exclusions replaced by
|
||||
positive includes for all uniquely-named generated variants.
|
||||
- Pre-existing ESLint violations fixed: `skill-manager-core.mjs:282`
|
||||
(`no-useless-assignment`) and `manage-skills.mjs:270` (`no-unused-vars`).
|
||||
- Pre-existing shellcheck findings fixed: SC2034 and SC2329 in
|
||||
`reviewer-runtime/run-review.sh`; SC2064 in test trap statements;
|
||||
SC2016 / SC2251 in verify scripts (suppress intentional patterns).
|
||||
- `pnpm run sync:pi` now calls the generator instead of
|
||||
`sync-pi-package-skills.sh`.
|
||||
- `docs/DEVELOPMENT.md` extended with generation workflow and metadata docs.
|
||||
- `CHANGELOG.md` created with package-metadata change callout.
|
||||
|
||||
### Full byte-equivalence diff (M3 vs pre-M3)
|
||||
|
||||
See `CHANGELOG.md` § "Byte-equivalence diff allow-list" for the complete
|
||||
documented diff between M3-generated output and the pre-M3 variants. The
|
||||
only permitted diffs are headers, `.generated-manifest.json`, `name` rename,
|
||||
and `"private": true`.
|
||||
|
||||
---
|
||||
|
||||
## Post-M2 state
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
+1
-1
@@ -116,7 +116,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/create-plan
|
||||
cp -R pi-package/skills/create-plan/* .pi/skills/create-plan/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
|
||||
+137
-20
@@ -167,34 +167,46 @@ container with Node 20.
|
||||
documented in `docs/CLEANUP-BASELINE.md`. Those will be fixed in a dedicated
|
||||
cleanup pass. No violations were introduced by M2.
|
||||
|
||||
## pnpm workspace policy (M1 exclusion-only)
|
||||
**M3 update:** `pnpm run check` is now **fully green**. All pre-existing lint
|
||||
violations have been fixed (2 ESLint errors, 7 shellcheck findings). The
|
||||
`verify:generated` check is now a real implementation (was a stub in M2).
|
||||
|
||||
The `pnpm-workspace.yaml` at the repo root implements the **non-mutating,
|
||||
exclusion-only** policy for M1:
|
||||
## pnpm workspace policy (updated in M3)
|
||||
|
||||
**Included** (canonical source packages):
|
||||
The `pnpm-workspace.yaml` at the repo root uses a **positive-include** policy
|
||||
introduced in M3. There are no negative-glob exclusions.
|
||||
|
||||
- `skills/atlassian/shared/scripts` — shared Atlassian runtime source
|
||||
- `skills/web-automation/codex/scripts` — provisional canonical copy; M3
|
||||
will rename and/or consolidate
|
||||
**Canonical source packages** (never generated):
|
||||
|
||||
**Excluded** (generated agent-variant directories):
|
||||
- `skills/atlassian/shared/scripts` — shared Atlassian TypeScript runtime
|
||||
- `skills/web-automation/shared` — shared web-automation runtime template
|
||||
|
||||
- `skills/atlassian/{codex,claude-code,cursor,opencode,pi}/scripts`
|
||||
- `skills/web-automation/{claude-code,cursor,opencode,pi}/scripts`
|
||||
- `pi-package/**`
|
||||
**Generated agent-variant packages** (uniquely named, positively included):
|
||||
|
||||
**Why exclusion-only in M1?**
|
||||
- `skills/atlassian/{claude-code,codex,cursor,opencode,pi}/scripts`
|
||||
→ names `@ai-coding-skills/atlassian-{claude-code,codex,cursor,opencode,pi}`
|
||||
- `skills/web-automation/{claude-code,codex,cursor,opencode,pi}/scripts`
|
||||
→ names `@ai-coding-skills/web-automation-{claude-code,codex,cursor,opencode,pi}`
|
||||
- `pi-package/skills/atlassian/scripts`
|
||||
→ name `@ai-coding-skills/atlassian-pi-mirror`
|
||||
- `pi-package/skills/web-automation/scripts`
|
||||
→ name `@ai-coding-skills/web-automation-pi-mirror`
|
||||
|
||||
The generated agent-variant directories contain `package.json` files with the
|
||||
same `name` field as the canonical source. Including them in the workspace
|
||||
would cause pnpm to complain about duplicate package names. Renaming them to
|
||||
unique names (e.g. `atlassian-skill-scripts-codex`) requires a generator-driven
|
||||
update that touches every generated file — this is deferred to **M3** to keep
|
||||
M1 byte-identical for those files.
|
||||
**Why unique names matter:**
|
||||
|
||||
After `pnpm install`, `git status` should show zero modifications to any file
|
||||
under the excluded directories. If it does not, the workspace config is broken.
|
||||
Each package in a pnpm workspace must have a distinct `name` field. In M1 all
|
||||
generated agent-variant packages shared the same non-unique name as their
|
||||
canonical source package. In M3 every package receives a scoped unique name
|
||||
of the form `@ai-coding-skills/<skill>-<agent>`, enabling pnpm to include them
|
||||
alongside canonical source packages without conflicts. The pi-package mirrors
|
||||
use the `-mirror` suffix to distinguish them from the `pi` agent variants.
|
||||
|
||||
All generated packages are `"private": true` and are never published to any
|
||||
registry.
|
||||
|
||||
After `pnpm install`, `git status` should show zero modifications to any
|
||||
package.json file under any generated directory. If it does not, the workspace
|
||||
config or generator is broken.
|
||||
|
||||
## How to interpret the baseline report
|
||||
|
||||
@@ -205,8 +217,113 @@ fails on a check, compare the output against the baseline:
|
||||
- If the failure does not appear in the baseline → it is a regression
|
||||
introduced by recent changes and must be fixed before merge.
|
||||
|
||||
## How variants are generated (M3)
|
||||
|
||||
Every agent-variant directory under `skills/<skill>/<agent>/` and every
|
||||
`pi-package/skills/<skill>/` mirror is **generator-owned**. Do not edit
|
||||
files inside these directories directly — edit the canonical source instead
|
||||
and run `pnpm run sync:pi` to regenerate.
|
||||
|
||||
### Canonical sources (non-generated)
|
||||
|
||||
These directories are **never** generated and are **never** inside a generated
|
||||
root. They are the single source of truth for all content.
|
||||
|
||||
| Skill | Canonical source |
|
||||
|-------|------------------|
|
||||
| `atlassian` | SKILL.md: `skills/atlassian/_source/<agent>/SKILL.md`; scripts: `skills/atlassian/shared/scripts/` |
|
||||
| `web-automation` | SKILL.md: `skills/web-automation/_source/<agent>/SKILL.md`; scripts: `skills/web-automation/shared/` |
|
||||
| `create-plan` | `skills/create-plan/_source/<agent>/` (SKILL.md + templates) |
|
||||
| `do-task` | `skills/do-task/_source/<agent>/` (SKILL.md + templates) |
|
||||
| `implement-plan` | `skills/implement-plan/_source/<agent>/SKILL.md` |
|
||||
| `reviewer-runtime` (base) | `skills/reviewer-runtime/run-review.sh`, `notify-telegram.sh` |
|
||||
|
||||
The `_source/` directories and `shared/` directories sit under the skill root
|
||||
**outside** every generated root. Stale-file detection (`verify:generated`)
|
||||
never traverses them.
|
||||
|
||||
### Generated roots (authoritative list)
|
||||
|
||||
All paths are relative to the repo root.
|
||||
|
||||
```text
|
||||
skills/atlassian/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/web-automation/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/create-plan/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/do-task/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/implement-plan/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/reviewer-runtime/pi/
|
||||
pi-package/skills/{atlassian,create-plan,do-task,implement-plan,web-automation}/
|
||||
```
|
||||
|
||||
### Contributor workflow
|
||||
|
||||
1. **Edit the canonical source** in the appropriate `_source/<agent>/`, `shared/`, or
|
||||
base `skills/reviewer-runtime/` directory.
|
||||
2. **Run the generator:**
|
||||
|
||||
```bash
|
||||
pnpm run sync:pi # regenerates all 31 generated roots
|
||||
```
|
||||
|
||||
3. **Verify no drift:**
|
||||
|
||||
```bash
|
||||
pnpm run verify:generated # must exit 0
|
||||
```
|
||||
|
||||
4. **Stage both the canonical source AND the generated output** in the same commit.
|
||||
Never commit a canonical change without regenerating.
|
||||
|
||||
### File-type-aware header policy
|
||||
|
||||
Every generated file (except JSON and `pnpm-lock.yaml`) receives a header
|
||||
identifying it as generated and pointing to the canonical source. Headers are
|
||||
inserted so they do not break parsers or tools:
|
||||
|
||||
| File type | Header form | Placement |
|
||||
|-----------|-------------|----------|
|
||||
| Markdown (with YAML front matter) | `<!-- ⚠️ GENERATED FILE ... -->` | After closing `---` |
|
||||
| Markdown (no front matter) | `<!-- ⚠️ GENERATED FILE ... -->` | Top of file |
|
||||
| Shell script | `# ⚠️ GENERATED FILE ...` | After `#!` shebang |
|
||||
| TypeScript / JavaScript | `// ⚠️ GENERATED FILE ...` | After `#!` shebang if present, else top |
|
||||
| YAML (non-lockfile) | `# ⚠️ GENERATED FILE ...` | Top of file |
|
||||
| JSON | *(no header — recorded in `.generated-manifest.json`)* | — |
|
||||
| `pnpm-lock.yaml` | *(no header — managed by pnpm)* | — |
|
||||
| JSONC | `// ⚠️ GENERATED FILE ...` | Top of file |
|
||||
|
||||
### `.generated-manifest.json` contract
|
||||
|
||||
Each generated root contains a `.generated-manifest.json` that:
|
||||
|
||||
- Has a `$schema` marker and a `generator` field for identification.
|
||||
- Lists every **other** generator-owned path in that root (relative path,
|
||||
file mode, SHA-256 hash, kind).
|
||||
- **Does NOT list itself** (non-self-referential).
|
||||
- Is scoped to exactly **one** generated root — there is no manifest at
|
||||
`skills/<skill>/`.
|
||||
- Is verified structurally (not byte-for-byte) by `verify:generated`.
|
||||
|
||||
### Package metadata (M3 change)
|
||||
|
||||
Each generated agent-variant `package.json` carries:
|
||||
|
||||
- A **unique private name** in the form `@ai-coding-skills/<skill>-<agent>` (e.g.
|
||||
`@ai-coding-skills/atlassian-claude-code`).
|
||||
- `"private": true` to prevent accidental npm publication.
|
||||
|
||||
The pi-package mirrors (`pi-package/skills/atlassian/scripts` and
|
||||
`pi-package/skills/web-automation/scripts`) use the `-mirror` agent suffix
|
||||
(`@ai-coding-skills/atlassian-pi-mirror`, `@ai-coding-skills/web-automation-pi-mirror`)
|
||||
to distinguish them from the `pi` agent variants in the workspace.
|
||||
|
||||
This replaces the previous non-unique `name` fields (`atlassian-skill-scripts`,
|
||||
`web-automation-scripts`). These packages are private and are never published.
|
||||
See `CHANGELOG.md` for the full rename list.
|
||||
|
||||
## Links
|
||||
|
||||
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline
|
||||
- [README.md](../README.md) — project overview
|
||||
- [docs/README.md](./README.md) — documentation index
|
||||
- [CHANGELOG.md](../CHANGELOG.md) — milestone-by-milestone change record
|
||||
|
||||
+1
-1
@@ -151,7 +151,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/do-task
|
||||
cp -R pi-package/skills/do-task/* .pi/skills/do-task/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
|
||||
@@ -124,7 +124,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/implement-plan
|
||||
cp -R pi-package/skills/implement-plan/* .pi/skills/implement-plan/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
|
||||
+15
-10
@@ -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
|
||||
|
||||
+4
-2
@@ -61,10 +61,12 @@ Reference docs for each skill family:
|
||||
### 7. Development
|
||||
|
||||
- [DEVELOPMENT.md](./DEVELOPMENT.md) — Prerequisites, `pnpm run check`,
|
||||
workspace policy, cross-platform shell support, and the transitional quality
|
||||
contract.
|
||||
workspace policy, generation workflow, cross-platform shell support, and the
|
||||
quality contract.
|
||||
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — As-is quality baseline
|
||||
captured at M1, updated through subsequent milestones.
|
||||
- [../CHANGELOG.md](../CHANGELOG.md) — Milestone-by-milestone change record
|
||||
(includes M3 package-metadata rename table).
|
||||
|
||||
## Repo Setup
|
||||
|
||||
|
||||
@@ -89,7 +89,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/web-automation
|
||||
cp -R pi-package/skills/web-automation/* .pi/skills/web-automation/
|
||||
cd .pi/skills/web-automation/scripts
|
||||
|
||||
Reference in New Issue
Block a user