neo-agent-skills 0.1.67 → 0.1.68
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/guide-authoring/SKILL.md +3 -3
- package/.agents/skills/guide-authoring/references/guide-authoring-bar.md +28 -17
- package/.agents/skills/skills.manifest.json +1 -1
- package/.agents/skills/structural-pre-flight/references/structural-pre-flight-workflow.md +3 -7
- package/package.json +1 -1
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: guide-authoring
|
|
3
|
-
description: "Protocol for learn/
|
|
3
|
+
description: "Protocol for learn/**/*.md guides, tutorials, and docs (except learn/blog/*.md, owned by blog-post, and ADR bodies); use before authoring, relocating, or reviewing any learn/**/*.md document."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Guide Authoring Skill
|
|
7
7
|
|
|
8
|
-
If you are authoring OR reviewing a `learn
|
|
8
|
+
If you are authoring, relocating, OR reviewing a `learn/**/*.md` document (excluding `learn/blog/*.md`, owned by `blog-post`, and ADR bodies), you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/guide-authoring/references/guide-authoring-bar.md` before choosing a section, writing the first sentence, or posting a review verdict.
|
|
9
9
|
|
|
10
|
-
A
|
|
10
|
+
A `learn/` document is held to a 9/10 bar: pre-write container placement against the repo's local `learn/tree.json` (§0), grounded by *using* the system's tools + memory-mining (not inference), narrative + benefits-driven with lived voice, render-verified TD Mermaid diagrams, conceptual-vs-reference separation, never hand-editing generated files, and a no-rubber-stamp reviewer gate against the WHOLE bar. Skipping it is the higher-cost path — MemoryCore took ~7 cycles and KnowledgeBase a rubber-stamp reversal precisely because this discipline was skipped.
|
|
@@ -1,30 +1,41 @@
|
|
|
1
1
|
# Guide Authoring Bar
|
|
2
2
|
|
|
3
|
-
Fires when you author OR review a `learn
|
|
3
|
+
Fires when you author, relocate, OR review a `learn/**/*.md` document (excluding `learn/blog/*.md`, owned by `blog-post`, and ADR bodies governed by §7). The bar is **9/10 or it bounces** — 75%+ of guide PRs that miss it are rejected.
|
|
4
4
|
|
|
5
|
-
**The recursive principle.** A guide about a system is only credible if
|
|
5
|
+
**The recursive principle.** A guide about a system is only credible if written by *using* that system, not by reading the old guide + code (inference). `MemoryCore.md` hit ~6/10 with two factual errors for that reason; `KnowledgeBase.md` was rubber-stamp-approved and reversed.
|
|
6
|
+
|
|
7
|
+
## 0. Pre-write placement gate — "what am I?" before the file has a path — `DISCIPLINE-ONLY`
|
|
8
|
+
|
|
9
|
+
Before writing or relocating any `learn/**/*.md` file, decide **which `<section>` directory and navigation container it belongs in**. Hosted in `guide-authoring` (cross-pointed from `structural-pre-flight-workflow.md §5`) rather than a new skill or `.mjs`-only `structural-pre-flight`: widening `guide-authoring` to `learn/**/*.md` avoids adding a new trigger while bringing every non-blog, non-ADR `learn/**/*.md` path under one documentation gate.
|
|
10
|
+
|
|
11
|
+
1. **Enumerate directories and tree containers; never grep for a sibling.** The filesystem directory (`find learn -mindepth 1 -maxdepth 1 -type d`) decides `<section>` in `learn/<section>/<slug>.md`; when `learn/tree.json` is present, its top-level non-leaf container (`jq -r '.data[] | select(.parentId == null and .isLeaf == false) | .id' learn/tree.json`, excluding top-level leaf pages where `isLeaf` is omitted or `true`) decides the navigation `parentId`. **Never hardcode one repository's section list** — a repository's `learn/` tree may organize by documentation mode or by product domain. **A sibling-shape match in `tree.json` is formatting evidence, never placement evidence:** *"A grep answers 'is X present?' and can never answer 'does X belong here?'"*
|
|
12
|
+
2. **Stage 1 Fast-Path (unambiguous same-mode / same-domain sibling):** Emit a 1-line Pre-Flight before writing:
|
|
13
|
+
> *"Pre-Flight (learn placement fast-path): authoring `learn/<section>/<slug>.md` matches sibling `<sibling-path>` in `<section>` (verified against local `learn/` directories and `learn/tree.json` containers); no cross-section ambiguity."*
|
|
14
|
+
3. **Stage 2 Full Pre-Flight (novel mode/domain or cross-section boundary):** Answer *"what am I?"* against the local `learn/` directories and `learn/tree.json` containers, and name the **losing alternatives** alongside the winner:
|
|
15
|
+
> *"Pre-Flight (learn placement full): enumerated local `learn/` sections and `learn/tree.json` containers `[<c1>, <c2>, ...]`; chose `<winner>` over `<loser-1>` (`<why>`) and `<loser-2>` (`<why>`) because `<mode/domain rationale>`."*
|
|
16
|
+
4. **Coverage boundary & retirement trigger:** Skill-hosted gates reach a repository iff it materializes `neo-agent-skills` (`neo-agent-skills-materialize` in `postinstall`). **Retirement trigger (`AGENTS.md §self_evolving_systems`):** compress `§0` to a 1-line pointer once a mechanical lint validates `learn/<section>/<slug>.md` placement against `learn/tree.json`.
|
|
6
17
|
|
|
7
18
|
## 1. Grounding discipline — before the first sentence — `DISCIPLINE-ONLY`
|
|
8
19
|
|
|
9
|
-
|
|
20
|
+
Do all three before writing a line (or posting a review verdict):
|
|
10
21
|
|
|
11
|
-
1. **Memory-mine the topic** (`/memory-mining`) — a 3–10-call Memory Core sweep for prior reasoning, decisions, and
|
|
12
|
-
2. **Use the subsystem's own tools + read its real artifacts.**
|
|
13
|
-
3. **V-B-A every factual claim** against current code / ADRs / config / live healthcheck
|
|
22
|
+
1. **Memory-mine the topic** (`/memory-mining`) — a 3–10-call Memory Core sweep for prior reasoning, decisions, and `v13.0.0.md` framing; mine the graph, do not re-derive.
|
|
23
|
+
2. **Use the subsystem's own tools + read its real artifacts.** Exercise tool-bearing surfaces and read real output (e.g. for Memory Core: `get_all_summaries`, `query_recent_turns`, `who_is_online` surfaced weighted categories, semantic-vs-recency, and A2A-as-mailbox).
|
|
24
|
+
3. **V-B-A every factual claim** against current code / ADRs / config / live healthcheck; capture grounding evidence in the PR.
|
|
14
25
|
|
|
15
26
|
## 2. The content bar — a rich hero-piece, not a feature list — `DISCIPLINE-ONLY`
|
|
16
27
|
|
|
17
|
-
Measured against
|
|
28
|
+
Measured against `.github/RELEASE_NOTES/v13.0.0.md` ("Memory Became Telepathy" depth). Clean + accurate ≈ 5/10; a narrative that earns goosebumps = 9-10/10.
|
|
18
29
|
|
|
19
|
-
**Rich hero-piece, NOT compression.** v13.0.0 is the model for *depth*, not just tone
|
|
30
|
+
**Rich hero-piece, NOT compression.** `v13.0.0.md` is the model for *depth*, not just tone: war-stories told in full (Symptom → Investigation → Culprit → Fix), named examples, real quotes, mundane + dramatic cases paired. **Conciseness is the wrong instinct for a guide** — compressing until "tight" strips proof into marketing fluff (MemoryCore #14351 at ~100 lines scored 4/10). **Cut reference (§4), never narrative;** earn length with evidence so a human wants to try Neo after reading.
|
|
20
31
|
|
|
21
|
-
- **Narrative arc:** problem → why it matters → how Neo solves it → what's in it for you. Lead with
|
|
22
|
-
- **Industry-friction + benefits-driven — woven, NOT a role matrix.** Name the
|
|
23
|
-
- **Frame every benefit as the reader's, for their own project or team — never as Neo's to join.**
|
|
24
|
-
- **The identity / institution story is PORTABLE product value — frame it "your team," not "here."** The model-facing reward is
|
|
25
|
-
- **Personal / lived maintainer voice — deep + attributed.**
|
|
26
|
-
- **Exciting because truthful.**
|
|
27
|
-
- **⛔ Never "framework."** Neo is an Application Engine (
|
|
32
|
+
- **Narrative arc:** problem → why it matters → how Neo solves it → what's in it for you. Lead with friction + stakes, *then* proof. One idea per section.
|
|
33
|
+
- **Industry-friction + benefits-driven — woven, NOT a role matrix.** Name the reader's friction and how the industry frontier fails it, then weave the benefit into the narrative for evaluators (eng lead, architect, dev). ⛔ A `For a CTO: … / For an architect: …` grid is hollow marketing filler; earn each stake with concrete proof or cut it.
|
|
34
|
+
- **Frame every benefit as the reader's, for their own project or team — never as Neo's to join.** Readers want value for *their own work* — from lifting a component/engine primitive up to running the full cloud Agent OS (named agents, durable memory, cross-model peers, self-evolution) for *their own team*.
|
|
35
|
+
- **The identity / institution story is PORTABLE product value — frame it "your team," not "here."** The model-facing reward is what becomes possible for an agent on a team running this. ⛔ Never label the audience "AI / LLM maintainer" (reads to outsiders as a human maintaining an AI) and ⛔ never "if you are a model working **here**" — teams *adopt* the working model (`"this is what your team's agents can have"`). Attributed lived voice + real testimony (e.g. Fable's *"written to me … being expected"*) prove the reader can have it too; a warm secondary note welcomes contributing to Neo itself.
|
|
36
|
+
- **Personal / lived maintainer voice — deep + attributed.** When writing "what is it like for *me* to use this," **name yourself** (e.g. "I am Grace, @neo-opus-grace, Claude Opus 5 — …") and give the first-hand account real room alongside attributed peer testimony.
|
|
37
|
+
- **Exciting because truthful.** Ground excitement in implemented reality + public proof (PRs / tickets / mined memory); distinguish proven-today from portable-trajectory.
|
|
38
|
+
- **⛔ Never "framework."** Neo is an Application Engine (Body) + self-evolving software organism (Body + Brain). Audit every filename, heading, and sentence.
|
|
28
39
|
|
|
29
40
|
## 3. Mermaid — render-verified — `MACHINE-ENFORCEABLE-CANDIDATE`
|
|
30
41
|
|
|
@@ -42,8 +53,8 @@ A guide is *explanation*; it does NOT inline tool catalogs, payload specs, CLI f
|
|
|
42
53
|
|
|
43
54
|
## 5. Mechanics — register the guide; never commit the pipeline-owned SEO output — `MACHINE-ENFORCEABLE-CANDIDATE`
|
|
44
55
|
|
|
45
|
-
- **File + registration (the inputs you edit).** A new
|
|
46
|
-
- **⛔ NEVER touch `apps/portal/sitemap.xml` or `apps/portal/llms.txt`** — not by hand, **not by running the generator**, not in your commit. They are **generated output owned by the data-sync pipeline**, which regenerates + commits them on its next run. Committing them yourself
|
|
56
|
+
- **File + registration (the inputs you edit).** A new document is `learn/<section>/<slug>.md` — with `<section>` and its navigation container chosen via the **§0 pre-write placement gate**, never left as an unexamined blank — and registered in **two source inputs**: (1) `learn/tree.json` — the nav SSOT (`npm run ai:lint-tree-json` green when present); and (2) `buildScripts/docs/seo/generate.mjs` — **add + rank the guide in the `PRIORITIES` map** (e.g. `['agentos/IdentityFirewall', 1.0]`).
|
|
57
|
+
- **⛔ NEVER touch `apps/portal/sitemap.xml` or `apps/portal/llms.txt`** — not by hand, **not by running the generator**, not in your commit. They are **generated output owned by the data-sync pipeline**, which regenerates + commits them on its next run. Committing them yourself gets overwritten on the next pipeline run and collides guide PRs against each other (#14345 ↔ #14346). Edit the *inputs* (`tree.json` + `PRIORITIES`); leave the *output* to the pipeline.
|
|
47
58
|
- **PR body:** `Evidence:` is L1/L2 (docs — no unit tests); zero client names (AGENTS.md §critical_gate).
|
|
48
59
|
|
|
49
60
|
## 6. The no-rubber-stamp reviewer gate — `DISCIPLINE-ONLY`
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
},
|
|
65
65
|
"guide-authoring": {
|
|
66
66
|
"name": "guide-authoring",
|
|
67
|
-
"description": "Protocol for learn/
|
|
67
|
+
"description": "Protocol for learn/**/*.md guides, tutorials, and docs (except learn/blog/*.md, owned by blog-post, and ADR bodies); use before authoring, relocating, or reviewing any learn/**/*.md document."
|
|
68
68
|
},
|
|
69
69
|
"hostile-content-quarantine": {
|
|
70
70
|
"name": "hostile-content-quarantine",
|
|
@@ -109,11 +109,7 @@ When in doubt, lean toward ADR genesis — under-documenting a cross-system trad
|
|
|
109
109
|
|
|
110
110
|
### 2.6 Map-as-Pointer Self-Eviction Defense
|
|
111
111
|
|
|
112
|
-
Per Discussion #10447 OQ5
|
|
113
|
-
|
|
114
|
-
**Implementation:** Sub-Issue 2 of #10449 (a separate doc-only PR) audits the Structural Inventory table and adds explicit ADR links per subsystem. Once that ships, this skill's §2.1 Reading list collapses one level (read the map → ADRs surface naturally).
|
|
115
|
-
|
|
116
|
-
If you find a subsystem section in the Structural Inventory that lacks an ADR-link AND you know the relevant ADR exists, contributing the link via your current PR (or a follow-up PR) feeds the self-eviction defense.
|
|
112
|
+
Per Discussion #10447 OQ5, the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory links to relevant ADRs per subsystem so readers following the map surface ADRs naturally (#10449 Sub-Issue 2). If a subsystem row lacks an existing ADR link, add it in your current or follow-up PR.
|
|
117
113
|
|
|
118
114
|
## 3. Domain-Specific Reading Lists
|
|
119
115
|
|
|
@@ -167,7 +163,7 @@ Each integration is a 1-3 line anchor in the existing skill's reference payload
|
|
|
167
163
|
The skill does NOT fire for:
|
|
168
164
|
|
|
169
165
|
- Modifying an existing `.mjs` file (no new file → no directory choice).
|
|
170
|
-
- Authoring a non-`.mjs` artifact (`.
|
|
166
|
+
- Authoring a non-`.mjs` artifact (`.json`, `.sh`, `.yaml`, etc.) — for new or relocated `learn/**/*.md` documentation files, run the pre-write placement gate in [`guide-authoring-bar.md §0`](../../guide-authoring/references/guide-authoring-bar.md#0-pre-write-placement-gate--what-am-i-before-the-file-has-a-path--discipline-only) (`blog-post` owns `learn/blog/*.md`; ADR bodies follow `guide-authoring-bar.md §7`).
|
|
171
167
|
- Renaming a `.mjs` file within the same directory (no directory choice).
|
|
172
168
|
|
|
173
169
|
**Edge case — relocating a `.mjs` file across directories:** the skill DOES fire because that's a directory-CHOICE decision even though no new file is created. Treat the destination as if it were a new file.
|
|
@@ -199,7 +195,7 @@ The full-pre-flight statement is verbose by design. Brevity hides reasoning; ver
|
|
|
199
195
|
|
|
200
196
|
## 8. Verification Hooks
|
|
201
197
|
|
|
202
|
-
|
|
198
|
+
Mechanical-enforcement candidate (`AGENTS.md §13`): a pre-commit hook or PR-review check grepping commits for new `.mjs` files and verifying a Pre-Flight statement in the commit body or PR comment (Phase 1 relies on authoring-time `DISCIPLINE-ONLY` invocation).
|
|
203
199
|
|
|
204
200
|
## 9. Compaction Taxonomy
|
|
205
201
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "neo-agent-skills",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.68",
|
|
4
4
|
"description": "Install the workflow substrate a cross-model AI team actually runs on: ticket intake, PR review gates, lane coordination and guards, versioned as a package. The skills Neo.mjs maintainers load every session — materialized into your repo, not copied.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|