gaia-research/gaia-skill-tree / .agents/skills/gaia-suite-intake
gaia-suite-intake
VerifiedComprehensive, reusable playbook for multi-component suite intake under Yggdrasil III. Audits component installability, maps origin candidates to generic capabilities, ingests named components with shared-repo baseline caps, manifests suites via gaia dev fuse, calibrates capstone and component ranks, and closes out via Class S regeneration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
SKILL.md
View on GitHub---
name: gaia-suite-intake
description: >
Comprehensive, reusable playbook for multi-component suite intake under Yggdrasil III.
Audits component installability, maps origin candidates to generic capabilities, ingests
named components with shared-repo baseline caps, manifests suites via gaia dev fuse,
calibrates capstone and component ranks, and closes out via Class S regeneration.
---
# gaia-suite-intake
End-to-end playbook for ingesting, structuring, and calibrating multi-component skill
suites under **Yggdrasil III**.
A **suite** is a cohesive collection of specialized skills authored by a contributor or team,
anchored by a central **capstone** skill that coordinates or unifies them (e.g. `gsd-build/get-shit-done`,
`leonxlnx/taste-skill`, `obra/superpowers`). Ingesting a suite requires orchestrating multiple
interlocking layers: component installability, generic capability mappings, shared repository
evidence capping, suite manifestation via `gaia dev fuse`, branch-aware calibration, and Class S
artifact regeneration.
---
## Yggdrasil III Normative Rules & Invariants
Before executing any intake steps, verify understanding of these foundational invariants:
1. **Type Axis Collapse**:
- The starless node `type` is strictly `{basic, fusion}`.
- `extra`, `ultimate`, and `unique` are **retired as types** — never write them to node JSON.
2. **Derived Branch Taxonomy**:
- Branch (`standard` / `suite` / `unique`) is derived dynamically, never hard-coded.
- A skill carrying `suiteComponents` sits on the **Suite branch** at any rank (1★–6★).
- Standalone skills without `suiteComponents` sit on `standard` (1★–3★) or `unique` (4★–6★).
3. **Trust Magnitude as Sole Promotion Authority**:
- The legacy per-star Evidence Floor is completely retired.
- `fusion-recipe` rows contribute **0 TM** (Issue #1600). Structural composition is
reported separately via **Fusion Score**, which gates no rank.
4. **Shared Repository Evidence Cap**:
- Sub-components inheriting repository evidence from a shared parent repo are capped at
`SUITE_COMPONENT_REPOSITORY_CAP = 49.9 TM` per component (`META.md` §2.1, `trustMagnitude.py`).
- Repository adoption alone grades a sub-component C (49.9 TM / 2★ ceiling). Grade B (3★)
needs at least one more scoring row of the component's own (founder ruling 2026-11-08).
5. **Branch-Aware 4★ Gate (`META.md` §4 / Issue #1741)**:
- **4★ Promotion Requirement**: Requires Overall Trust Grade A (TM ≥ 100) and live verified
blob evidence (The Star Bar, `META.md` §2.4).
- **Unique Branch** (standalone, no `suiteComponents`): 4★ Unique requires being its bucket's
automatic Origin (highest merit, `META.md` §4.1); no fusion-prerequisite Origin.
- **Suite Branch** (capstone carrying `suiteComponents`): 4★ Extra does **NOT** require
bucket-level Origin on its generic bucket. The capstone represents the suite cluster rather
than a single generic bucket monopoly. Suite origin requirements apply at **5★ Ultimate**
(proposer must hold Origin on ≥1 of the `suiteComponents` per `META.md` §4.2).
- *Precedents*: `leonxlnx/taste-skill` (4★ Extra, `origin: false` on generic `design-generation`),
`gsd-build/get-shit-done` (4★ Extra).
---
## Inputs
Gather these before beginning:
| Input | Description | Example |
|---|---|---|
| `contributor` | GitHub organization or username | `leonxlnx` |
| `suite-slug` | Identifier for the suite capstone | `taste-skill` |
| `repo-url` | Canonical GitHub repository URL | `https://github.com/leonxlnx/taste-skill` |
| `default-branch` | Default git branch of the upstream repo | `main` |
| `components` | List of sub-skill directories / files | `brandkit`, `minimalist-skill`, ... |
---
## Phase 1: Upstream Suite Inspection & Installability Audit
Inspect the upstream repository structure and audit every component before touching the registry.
### 1.1 Repo Structure & Component Identification
Inspect the remote repository using `gh` or clone locally in a temporary directory:
```bash
gh repo view <owner>/<repo> --json defaultBranchRef,stargazerCount,description
```
Locate all component `SKILL.md` files:
- Typical layouts: `skills/<component-name>/SKILL.md`, `plugins/<name>/SKILL.md`, or top-level directories.
- Identify the **capstone**: the primary entry point, meta-orchestrator, or root skill that references or coordinates the components.
### 1.2 Frontmatter & Lifecycle Audit
For each component `SKILL.md`, verify:
- Frontmatter exists with valid YAML fences (`---`).
- Required fields: `name`, `description`.
- Instructions / CLI usage: verify how the skill is executed (e.g. `npx`, `uvx`, shell script, or harness prompt).
### 1.3 The Star Bar (Installability Gate)
Per `META.md` §2.4:
- Any skill promoted to **3★ or higher MUST have a verified GitHub BLOB link** pointing to a concrete file (e.g. `https://github.com/<owner>/<repo>/blob/<branch>/.../SKILL.md`), never a bare repo root.
- A missing verified blob link is a hard reset to 1★ (Awakened).
- Construct the exact blob URL for every component and confirm HTTP 200 reachable.
---
## Phase 2: Origin Candidate Analysis & Generic Mapping
Map every component (and the capstone) to a generic capability bucket in `registry/nodes/`.
### 2.1 Capability Resolution
For each component:
1. Search existing generic nodes:
```bash
grep -rn "name: " registry/nodes/
# or search by id slug
find registry/nodes -name "*.json" | grep -i "<keyword>"
```
2. If a matching generic bucket exists:
- Check existing named implementations in that bucket:
```bash
grep -rl "genericSkillRef: <generic-id>$" registry/named/
```
- If bucket has no implementations, the incoming component will be its Origin once built.
- If bucket has implementations, Origin goes automatically to the highest merit (published level, then TM; ties all hold it). Do not set `origin` yourself.
3. If no matching generic capability exists:
- Create a starless generic `basic` node:
```bash
gaia dev add <new-generic-id> \
--name "<Generic Capability Name>" \
--description "<Precise, vendor-agnostic capability description>" \
--type basic \
--no-build
```
- The incoming component is the sole implementation and therefore becomes the Origin automatically.
---
## Phase 3: Ingestion of Named Components & Evidence Scoring
Ingest components programmatically via `gaia dev` verbs. Never hand-edit JSON or frontmatter.
### 3.1 Register Named Skills
For each component:
```bash
gaia dev add --named <contributor>/<component-slug> \
--generic-ref <generic-id> \
--name "<Component Display Name>" \
--title "<RPG Title / Clean Name>" \
--description "<Component description>" \
--links github="https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md" \
--no-build
```
Also register the named capstone:
```bash
gaia dev add --named <contributor>/<suite-slug> \
--generic-ref <capstone-generic-id> \
--name "<Suite Capstone Display Name>" \
--title "<Suite Title>" \
--description "<Suite overview description>" \
--links github="https://github.com/<owner>/<repo>/blob/<branch>/<path-or-readme>" \
--no-build
```
### 3.2 Add Verified Evidence Rows
Gather verified repository metrics from GitHub API:
- `stargazerCount`: Total stars on the suite repository.
- `commits`: Total commit count.
- `contributors`: Total contributor count.
- `createdAt` / `sourceStartedAt`: Creation timestamp of repo/file.
#### A. Capstone Evidence
Add repository adoption evidence to the capstone:
```bash
gaia dev evidence <contributor>/<suite-slug> \
--type github-stars-own \
--source "https://github.com/<owner>/<repo>/blob/<branch>/<path>" \
--stars <stargazerCount> \
--source-started-at "<YYYY-MM-DD>" \
--notes "<stars> stars on <owner>/<repo> repository" \
--no-build
gaia dev evidence <contributor>/<suite-slug> \
--type repo-own \
--source "https://github.com/<owner>/<repo>" \
--commits <commitCount> \
--contributors <contributorCount> \
--source-started-at "<YYYY-MM-DD>" \
--notes "<commits> commits, <contributors> contributors" \
--no-build
```
#### B. Component Evidence & Shared Repo Cap
Add component-level evidence. Sub-components residing in the shared repository inherit
adoption signals, but Yggdrasil III enforces:
- `skillCountInRepo`: Set to the total number of components sharing the repository.
- `SUITE_COMPONENT_REPOSITORY_CAP = 49.9 TM`: The scoring engine automatically bounds
shared repository evidence so that adoption alone caps at 49.9 TM (Grade C).
```bash
gaia dev evidence <contributor>/<component-slug> \
--type github-stars-own \
--source "https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md" \
--stars <stargazerCount> \
--skill-count <componentCount> \
--source-started-at "<YYYY-MM-DD>" \
--no-build
```
---
## Phase 4: Suite Manifestation via `gaia dev fuse`
**Critical Rule**: Running `gaia dev update-named --suite-components` alone is **insufficient**.
`gaia dev docs` and `gaia dev build` will strip `suiteComponents` from Named Skill frontmatter
unless a backing suite manifest exists at `registry/suites/<contributor>/<suite-slug>.json`.
Use `gaia dev fuse` to establish the manifest and wire the graph in one atomic operation:
```bash
gaia dev fuse <generic-suite-id> \
--name "<Suite Name>" \
--description "<Suite fusion description>" \
--prereqs <comp1-generic-id>,<comp2-generic-id>,... \
--named-capstone <contributor>/<suite-slug> \
--suite-components <contributor>/<comp1>,<contributor>/<comp2>,... \
--no-build
```
### Verification:
1. Confirm manifest exists: `test -f registry/suites/<contributor>/<suite-slug>.json`
2. Confirm frontmatter wiring:
```bash
grep -c "suiteComponents:" registry/named/<contributor>/<suite-slug>.md
```
---
## Phase 5: Calibration of Capstone & Component Origins
### 5.1 Appraise Trust Magnitude
Run the appraisal tool on the capstone and all components:
```bash
python scripts/trust_appraise.py --skill <contributor>/<suite-slug>
```
Or use the detailed inspector:
```bash
GAIA_OPERATOR_OVERRIDE=1 PYTHONPATH=src python3 scripts/inspectTrustMagnitude.py --skill <contributor>/<suite-slug>
```
Verify:
- Capstone TM score and Overall Trust Grade.
- `fusionScore`: Structural composition reading (informational, does not feed TM).
### 5.2 Capstone Calibration (4★ Extra)
Evaluate the promotion gate:
- **Condition**: Capstone has Overall Trust Grade A (TM ≥ 100) and verified blob link.
- **Suite Branch Invariant**: Capstone does **NOT** require bucket-level Origin on its generic bucket!
Origin on generic bucket is strictly for Unique branch standalone skills (`META.md` §4.1).
Suite origin requirements apply at 5★ Ultimate (Origin on ≥1 suiteComponent per `META.md` §4.2).
- Apply calibration:
```bash
gaia dev calibrate <contributor>/<suite-slug> 4★ --no-build
```
### 5.3 Component Calibration (Origin is automatic)
1. **Origin**: nothing to do. `gaia dev docs` derives each bucket's Origin from merit
(`META.md` §4.1); `gaia dev update-named --origin` refuses.
2. **Component Star Calibration**:
Calibrate each component to its TM grade band:
- Grade B (TM ≥ 50) → `3★` (must have verified blob link)
- Grade C (TM ≥ 20) → `2★`
- Ungraded (TM < 20) → `1★`
```bash
gaia dev calibrate <contributor>/<component-slug> <N★> --no-build
```
---
## Phase 6: Single-PR Closeout with Class S Documentation Generation
### 6.1 Single Dev Build
Run exactly one build pass to compile the registry and generate Class S site assets:
```bash
GAIA_OPERATOR_OVERRIDE=1 PYTHONPATH=src python3 -m gaia_cli.main dev build
```
### 6.2 Preflight Hygiene & Staging
Use `scripts/review_meta_close.py` to prevent leaks, drop CRLF noise, and stage only allowlisted artifacts:
```bash
# 1. Review status (must show 0 leaks in PR)
python scripts/review_meta_close.py status -v
# 2. Stage intended artifacts for this contributor
python scripts/review_meta_close.py stage --contributor <contributor> --apply
# 3. Verify clean index
python scripts/review_meta_close.py check
# 4. Run UTF-8 safe validation
python scripts/review_meta_close.py validate
```
### 6.3 Staged Artifacts Checklist
Verify that git diff includes only:
- `registry/nodes/` (new/updated generic nodes)
- `registry/named/<contributor>/` (capstone and component `.md` files)
- `registry/suites/<contributor>/<suite-slug>.json` (suite manifest)
- `registry/named-skills.json` & tracked registry files
- `docs/graph/` (Class S graph assets: `gaia.json`, `gaia.gexf`, `named/index.json`)
- `docs/badges/_assets/<contributor>/` & `docs/og/<contributor>/`
### 6.4 Branch & PR Opening
```bash
git checkout -b review/meta/<contributor>-<suite-slug>
git commit -m "feat(suite): ingest <contributor>/<suite-slug> suite with <N> components"
git push origin review/meta/<contributor>-<suite-slug>
gh pr create --title "feat(suite): ingest <contributor>/<suite-slug> suite" \
--body "Ingests <contributor>/<suite-slug> suite under Yggdrasil III. Calibrates capstone to 4★ Extra on Grade A TM."
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |