Skip to content

Commit dcf7739

Browse files
rezaquantrezaquant
committed
Establish Pepsy skill governance
1 parent f8ac1c5 commit dcf7739

9 files changed

Lines changed: 461 additions & 94 deletions

File tree

‎.github/skills/README.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,19 @@
33
Each skill is self-contained in one directory with a required `SKILL.md` and
44
optional `references/` and `agents/` subdirectories.
55

6+
Start with [`pepsy-maintainer/SKILL.md`](pepsy-maintainer/SKILL.md) for a
7+
cross-cutting task. The repository-level
8+
[`agent-bundle.yaml`](agent-bundle.yaml) is the upload map for the Pepsy
9+
Maintainer Workspace Agent; it separates stable references, core skills, and
10+
optional domain skills. Keep the skill directories flat and upload
11+
`SKILL.md` plus any `references/**`; `agents/openai.yaml` is local UI metadata,
12+
not ordinary agent context.
13+
14+
Read [`SKILL_POLICY.md`](SKILL_POLICY.md) before adding, renaming, merging,
15+
deprecating, or removing a skill. It defines the selection workflow, package
16+
contract, lifecycle, and quality gate. Run the catalog validator after any
17+
catalog or skill-package change.
18+
619
## Core workflows
720

821
- [MPS optimizer](mps-optimizer/SKILL.md)
@@ -22,6 +35,6 @@ When adding a skill, follow the same layout and add it to this catalog. Keep
2235
shared repository rules in `AGENTS.md`; keep skill-specific procedures here.
2336

2437
All user-facing skills also carry `agents/openai.yaml` metadata so the catalog
25-
and invocation chips stay consistent. Tree stabilizer work composes the Tree
26-
Optimizer and Stabilizer Tensor Network skills rather than duplicating their
38+
and invocation chips stay consistent. The maintainer router and Tree
39+
Stabilizer skill compose the domain skills rather than duplicating their
2740
shared invariants.

‎.github/skills/SKILL_POLICY.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Pepsy skill policy
2+
3+
This file is the source of truth for designing and maintaining the local
4+
Pepsy skills under `.github/skills/`. It governs the skill catalog itself; it
5+
does not replace domain-specific invariants in an individual `SKILL.md`.
6+
7+
## Design principles
8+
9+
- Keep one skill focused on one reusable subsystem or workflow. Do not create
10+
a skill for a single class, one-off investigation, or information already
11+
covered by an existing skill.
12+
- Keep repository-wide rules in `AGENTS.md` and cross-cutting routing in
13+
`pepsy-maintainer/SKILL.md`. Keep numerical and API invariants in the owning
14+
domain skill.
15+
- Prefer composition over duplication. A cross-domain skill may point to the
16+
owning skills; it must not copy their invariants and let the copies drift.
17+
- Optimize for progressive disclosure: concise `SKILL.md` first, one-level
18+
`references/` only for details needed by a subset of tasks.
19+
20+
## Package contract
21+
22+
Every skill is a flat directory with this shape:
23+
24+
```text
25+
.github/skills/<name>/
26+
├── SKILL.md # required instructions and trigger metadata
27+
├── agents/openai.yaml # required local UI metadata
28+
├── references/ # optional, direct supporting material
29+
└── scripts/ # optional, deterministic local helpers
30+
```
31+
32+
Required rules:
33+
34+
- Use lowercase hyphen-case for `<name>`, matching the `name` frontmatter.
35+
- `SKILL.md` frontmatter contains only `name` and `description`. Put all
36+
trigger conditions in `description`; do not hide them in a body section.
37+
- Keep `SKILL.md` under 500 lines. Move detailed method notes, API maps, and
38+
variant-specific guidance to direct `references/` files.
39+
- Keep references one level deep and link them from `SKILL.md`. Do not add
40+
README, CHANGELOG, installation, or quick-reference files inside a skill.
41+
- Keep `agents/openai.yaml` synchronized with the skill name and purpose.
42+
- Add every skill to `.github/skills/README.md` and
43+
`.github/skills/agent-bundle.yaml` with the correct role and upload files.
44+
45+
## How to use skills
46+
47+
1. Read the repository `AGENTS.md` and inspect Git status before editing.
48+
2. Classify the request as cross-cutting or domain-specific.
49+
3. For cross-cutting work, read `pepsy-maintainer/SKILL.md`, then load the
50+
smallest set of domain skills that own the affected code or invariants.
51+
4. For a focused task, read only the matching domain skill and its direct
52+
references. Do not load the full catalog by default.
53+
5. If two skills overlap, identify the primary owner and use the other only
54+
for its explicit interface or invariant. Report the selected skills.
55+
6. Read the closest source, tests, and API docs after the skill guidance.
56+
7. Validate the skill/catalog changes separately from package behavior; run
57+
focused package tests when implementation behavior also changes.
58+
59+
## Adding a skill
60+
61+
Add a skill only when all of these are true:
62+
63+
- The subsystem has a stable public or implementation boundary.
64+
- Users will ask for it repeatedly and its correct workflow is not obvious
65+
from the source alone.
66+
- The skill has clear trigger language and a clear owner namespace.
67+
- Its rules cannot be expressed more cleanly by extending an existing skill.
68+
69+
Use this sequence:
70+
71+
1. Search existing skills, `AGENTS.md`, docs, and source for overlap.
72+
2. Choose a short hyphen-case name and define concrete trigger phrases.
73+
3. Create the package with `SKILL.md` and `agents/openai.yaml`; add
74+
`references/` or `scripts/` only when needed.
75+
4. Write the smallest reliable workflow, including boundaries, invariants,
76+
source/test paths, and validation commands.
77+
5. Add the skill to the catalog and upload manifest. Update the maintainer
78+
router only if the new routing is not already covered.
79+
6. Run `quick_validate.py` for the new skill and
80+
`python .github/skills/pepsy-maintainer/scripts/validate_catalog.py`.
81+
7. Forward-test a representative request. If implementation behavior changed,
82+
run the owning focused tests and Ruff as required by `AGENTS.md`.
83+
84+
## Updating, deprecating, and removing
85+
86+
- Update the skill in the same change as the code/API workflow it documents.
87+
Remove stale claims; do not preserve historical behavior as active guidance.
88+
- When a subsystem moves, update source links, tests, namespace examples,
89+
catalog entries, and the upload manifest together.
90+
- Before deprecating a skill, search the repository and agent bundle for its
91+
name, links, and trigger phrases. Add a replacement route to the maintainer
92+
skill and catalog before removing it.
93+
- Remove a skill only after its replacement is documented, references are
94+
migrated, and validation passes. Never delete a skill merely because it is
95+
currently unused in one task.
96+
- Do not silently merge two skills. Keep the clearer owner, move unique
97+
guidance deliberately, then remove duplicate references and update routing.
98+
99+
## Quality gate
100+
101+
For every skill/catalog change, require:
102+
103+
```bash
104+
source ~/envs/py312/bin/activate
105+
python /home/reza.haghshenas@quantinuum.com/.codex/skills/.system/skill-creator/scripts/quick_validate.py .github/skills/<name>
106+
python .github/skills/pepsy-maintainer/scripts/validate_catalog.py
107+
git diff --check
108+
```
109+
110+
For a skill that governs implementation behavior, also run the closest
111+
focused test and `python -m ruff check src tests`. For cross-cutting changes,
112+
run the full suite according to `AGENTS.md`, or explicitly report why it was
113+
not run.

‎.github/skills/agent-bundle.yaml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
schema: 1
2+
name: Pepsy Maintainer
3+
description: Maintain and improve the Pepsy tensor-network package.
4+
5+
# This is a repository-level upload map, not a skill package. Keep the
6+
# package directories below flat so local discovery and relative references
7+
# remain stable.
8+
agent:
9+
repository: quantinuum-dev/pepsy
10+
branch_workflow: develop-to-main
11+
memory: per_user
12+
external_apps: []
13+
14+
# These are the small, stable context files to upload before domain skills.
15+
references:
16+
- AGENTS.md
17+
- README.md
18+
- pyproject.toml
19+
- docs/development/package_layout.md
20+
- .github/skills/SKILL_POLICY.md
21+
- .github/skills/README.md
22+
23+
# Upload SKILL.md and any files under references/ for the selected package.
24+
# agents/openai.yaml is local UI metadata; do not upload it as ordinary agent
25+
# context. The maintainer router is useful when the agent must choose a skill.
26+
skills:
27+
- name: pepsy-maintainer
28+
path: .github/skills/pepsy-maintainer
29+
role: router
30+
upload: [SKILL.md]
31+
- name: mps-optimizer
32+
path: .github/skills/mps-optimizer
33+
role: core
34+
upload: [SKILL.md]
35+
- name: tree-optimizer
36+
path: .github/skills/tree-optimizer
37+
role: core
38+
upload: [SKILL.md, references/**]
39+
- name: stabilizer-tensor-networks
40+
path: .github/skills/stabilizer-tensor-networks
41+
role: domain
42+
upload: [SKILL.md, references/**]
43+
- name: tree-stabilizer-optimizer
44+
path: .github/skills/tree-stabilizer-optimizer
45+
role: domain
46+
upload: [SKILL.md]
47+
- name: symdmrg2
48+
path: .github/skills/symdmrg2
49+
role: domain
50+
upload: [SKILL.md]
51+
- name: belief-propagation
52+
path: .github/skills/belief-propagation
53+
role: domain
54+
upload: [SKILL.md]
55+
- name: pepsy-vmc
56+
path: .github/skills/pepsy-vmc
57+
role: domain
58+
upload: [SKILL.md, references/**]
59+
- name: pepsy-fermion-operators
60+
path: .github/skills/pepsy-fermion-operators
61+
role: domain
62+
upload: [SKILL.md, references/**]
63+
- name: qmera-energy-optimizer
64+
path: .github/skills/qmera-energy-optimizer
65+
role: optional-domain
66+
upload: [SKILL.md, references/**]
67+
68+
# Recommended Agent Studio order: add the router and core skills first, then
69+
# only the domain skills needed by the agent's work. Native skill attachment
70+
# is preferred; use the upload entries above when the UI exposes files only.

‎.github/skills/pepsy-maintainer/SKILL.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
name: pepsy-maintainer
3+
description: 'Plan, implement, review, and validate focused changes in the Pepsy tensor-network package. Use for cross-cutting Pepsy maintenance, package layout, public API, tests, documentation, CI, or branch-workflow tasks; route specialized numerical work to the matching domain skill.'
4+
---
5+
6+
# Pepsy Maintainer
7+
8+
Use this as the entry point for work in `quantinuum-dev/pepsy`. It is a
9+
router, not a replacement for the domain skills below.
10+
11+
## Startup and scope
12+
13+
1. Read the repository [`AGENTS.md`](../../../AGENTS.md) and inspect
14+
`git status --short --branch` before editing.
15+
2. For any skill add/update/deprecation/removal, read the catalog
16+
[`SKILL_POLICY.md`](../SKILL_POLICY.md) before editing the skill tree.
17+
3. Keep edits inside Pepsy. Do not change Tensy, Gaugy, examples, or sibling
18+
repositories as part of a Pepsy task.
19+
4. Use canonical `pepsy.<domain>` namespaces and preserve the `develop` →
20+
`main` workflow. Never push, merge, release, delete data, or stage
21+
unrelated changes without explicit approval.
22+
5. Read only the domain skill(s) needed for the task. Keep focused tests,
23+
Ruff, and the full suite proportional to the change; report anything not
24+
run and any remaining risk.
25+
26+
## Domain routing
27+
28+
- MPS replay, layouts, or canonicalization → [`mps-optimizer`](../mps-optimizer/SKILL.md)
29+
- Tree replay, TTN layout, trajectories, or measurement → [`tree-optimizer`](../tree-optimizer/SKILL.md)
30+
- Stabilizer tensor networks → [`stabilizer-tensor-networks`](../stabilizer-tensor-networks/SKILL.md)
31+
- Tree stabilizer simulation → [`tree-stabilizer-optimizer`](../tree-stabilizer-optimizer/SKILL.md)
32+
- Symmetry-conserving DMRG2 → [`symdmrg2`](../symdmrg2/SKILL.md)
33+
- Belief propagation or loop/PNE methods → [`belief-propagation`](../belief-propagation/SKILL.md)
34+
- Torch/NetKet/JAX variational Monte Carlo → [`pepsy-vmc`](../pepsy-vmc/SKILL.md)
35+
- Fermion operators, Symmray charges, or fermionic gates → [`pepsy-fermion-operators`](../pepsy-fermion-operators/SKILL.md)
36+
- qMERA energy optimization → [`qmera-energy-optimizer`](../qmera-energy-optimizer/SKILL.md)
37+
38+
When a change crosses domains, read the maintainer skill first and then the
39+
smallest set of domain skills that own the affected invariants. Do not copy
40+
their rules into this router.
41+
42+
For skill-catalog work, run
43+
`python .github/skills/pepsy-maintainer/scripts/validate_catalog.py` after
44+
the individual skill validator and before reporting completion.
45+
46+
## Handoff
47+
48+
Use [`.github/skills/agent-bundle.yaml`](../agent-bundle.yaml) as the
49+
canonical list of files for a Workspace Agent. In a local checkout, the
50+
relative links above are authoritative. In Agent Studio, preserve the
51+
`references/skills/<name>/SKILL.md` target paths when uploading reference
52+
copies so the same routing remains readable.
53+
54+
Finish with changed files, branch, focused tests, Ruff/full-suite status,
55+
commit or push status, and remaining risks.

‎.github/skills/pepsy-maintainer/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Pepsy Maintainer"
3+
short_description: "Route Pepsy maintenance work to the right skill"
4+
default_prompt: "Use $pepsy-maintainer to plan and validate focused Pepsy package maintenance."

0 commit comments

Comments
 (0)