feat(M3): Shared-source generator for agent variants
This commit is contained in:
Stefano Fiorini
+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
|
||||
|
||||
Reference in New Issue
Block a user