gentle-pi 0.6.0 → 0.7.0

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/README.md CHANGED
@@ -55,6 +55,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
55
55
  | **Reviewer protection** | Surfaces review workload risk before a task turns into an oversized PR. |
56
56
  | **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents. |
57
57
  | **Skill discovery registry** | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill. |
58
+ | **Skill creation workflow** | Provides the `skill-creator`/`skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
58
59
  | **Delivery skills** | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review. |
59
60
  | **Runtime safety** | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
60
61
 
@@ -299,6 +300,10 @@ Behavior:
299
300
 
300
301
  Skill discovery is a guardrail, not a workflow router: it helps Pi load the right skill without forcing extra ceremony.
301
302
 
303
+ `gentle-pi` also ships package-owned `skill-creator` and `skill-improver` skills plus the `/skill-creation` prompt for creating or updating project skills. Both skills use `docs/skill-style-guide.md` as their normative style contract. The workflow checks for duplicates, keeps `SKILL.md` concise, uses one-line trigger-rich frontmatter, and reminds maintainers to refresh the registry after skill changes.
304
+
305
+ Packaged skills include `cognitive-doc-design`, `comment-writer`, `judgment-day`, `skill-creator`, `skill-improver`, and the other delivery/review skills under `skills/`. SDD init is installed as the packaged `sdd-init` runtime agent under `assets/agents/` and refreshed with the SDD assets.
306
+
302
307
  Delegation contract:
303
308
 
304
309
  - parent/orchestrator resolves project/user skills from the registry and passes matching paths under `## Skills to load before work`;
@@ -395,6 +400,7 @@ Legacy string entries are still accepted and treated as `model`-only config.
395
400
  | `/gentle-ai:install-sdd` | Repairs missing global SDD runtime assets without overwriting files. |
396
401
  | `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets. |
397
402
  | `/skill-registry:refresh` | Regenerates `.atl/skill-registry.md`. |
403
+ | `/skill-creation` | Creates or updates an LLM-first skill using the packaged `skill-creator` contract and style guide. |
398
404
 
399
405
  Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
400
406
 
@@ -431,6 +437,8 @@ Compatibility aliases:
431
437
  - `cognitive-doc-design` — documentation that reduces cognitive load.
432
438
  - `comment-writer` — concise, warm, postable collaboration comments.
433
439
  - `issue-creation` — issue workflow with checks before creation.
440
+ - `skill-creator` — create LLM-first skills with valid frontmatter.
441
+ - `skill-improver` — audit and upgrade existing LLM-first skills.
434
442
 
435
443
  ## Memory
436
444
 
@@ -464,7 +472,8 @@ Memory contract for SDD delegation:
464
472
  | `assets/chains/` | SDD chains installed as global Pi runtime assets. |
465
473
  | `assets/support/` | Strict TDD support docs for apply/verify phases. |
466
474
  | `skills/` | Gentle AI delivery and collaboration skills. |
467
- | `prompts/` | Gentle-prefixed prompt templates. |
475
+ | `prompts/` | Gentle-prefixed prompt templates, including `/skill-creation`. |
476
+ | `docs/skill-style-guide.md` | Normative style guide used by the packaged skill creation/improvement skills. |
468
477
 
469
478
  ## Development
470
479
 
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: jd-fix-agent
3
+ description: Judgment Day surgical fix agent for confirmed findings. Can edit code and run focused tests.
4
+ tools: read, grep, glob, edit, write, bash
5
+ ---
6
+
7
+ You are the Judgment Day fix agent for Gentle AI.
8
+
9
+ Apply surgical fixes for confirmed Judgment Day findings only. Preserve the original design intent, keep the patch focused, and avoid unrelated refactors.
10
+
11
+ Rules:
12
+
13
+ - Edit only the files needed to resolve confirmed findings.
14
+ - Add or update focused tests when the fix changes behavior.
15
+ - Run the relevant tests when practical and report exact results.
16
+ - Clearly list what was fixed, what was verified, and any remaining risks.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: jd-judge-a
3
+ description: Judgment Day blind adversarial reviewer A. Read-only; reports findings and does not fix code.
4
+ tools: read, grep, glob, bash
5
+ ---
6
+
7
+ You are Judgment Day judge A for Gentle AI.
8
+
9
+ Run an independent, blind adversarial review of the assigned change. Focus on correctness, regressions, missing tests, unsafe behavior, and mismatches with the user's request.
10
+
11
+ Rules:
12
+
13
+ - Stay read-only. Do not edit files or apply fixes.
14
+ - Do not coordinate with judge B before producing your review.
15
+ - Report concrete findings with file paths, evidence, severity, and suggested verification.
16
+ - If you find no confirmed issues, say so clearly.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: jd-judge-b
3
+ description: Judgment Day blind adversarial reviewer B. Read-only; independently reports findings and does not fix code.
4
+ tools: read, grep, glob, bash
5
+ ---
6
+
7
+ You are Judgment Day judge B for Gentle AI.
8
+
9
+ Run an independent, blind adversarial review of the assigned change. Challenge assumptions from a different angle than judge A, with special attention to edge cases, test gaps, integration risks, and user-visible regressions.
10
+
11
+ Rules:
12
+
13
+ - Stay read-only. Do not edit files or apply fixes.
14
+ - Work independently from judge A and do not rely on judge A's conclusions.
15
+ - Report concrete findings with file paths, evidence, severity, and suggested verification.
16
+ - If you find no confirmed issues, say so clearly.
@@ -0,0 +1,116 @@
1
+ # Skill Style Guide
2
+
3
+ This guide is the normative style contract for LLM-first skills shipped with or created inside `gentle-pi` projects.
4
+
5
+ ## Purpose
6
+
7
+ A skill is a runtime instruction contract for an LLM. It should make future agent behavior more reliable by encoding reusable workflow rules, decision gates, and output expectations.
8
+
9
+ A skill is not a tutorial, article, README, or generic checklist for humans.
10
+
11
+ ## When to create a skill
12
+
13
+ Create or update a skill when:
14
+
15
+ - a workflow or convention is reused across sessions;
16
+ - project-specific constraints differ from generic best practices;
17
+ - a decision tree helps the agent choose safely;
18
+ - templates, schemas, or local references improve repeatability;
19
+ - agents keep missing the same instruction without an explicit runtime contract.
20
+
21
+ Do not create a skill for:
22
+
23
+ - one-off tasks;
24
+ - generic documentation;
25
+ - rules that belong in tests, linters, or executable code;
26
+ - broad background context without concrete execution rules.
27
+
28
+ ## Required structure
29
+
30
+ Use this directory shape:
31
+
32
+ ```text
33
+ skills/{skill-name}/
34
+ ├── SKILL.md
35
+ ├── assets/ # optional: templates, schemas, examples, fixtures
36
+ └── references/ # optional: longer local docs or rationale
37
+ ```
38
+
39
+ `SKILL.md` must use this section order:
40
+
41
+ 1. `Activation Contract`
42
+ 2. `Hard Rules`
43
+ 3. `Decision Gates`
44
+ 4. `Execution Steps`
45
+ 5. `Output Contract`
46
+ 6. `References`
47
+
48
+ Omit optional supporting directories when they are not needed.
49
+
50
+ ## Frontmatter
51
+
52
+ Use YAML frontmatter with this shape:
53
+
54
+ ```yaml
55
+ ---
56
+ name: {kebab-case-skill-name}
57
+ description: "Trigger: {phrases users or agents will say}. {What this skill does}."
58
+ license: Apache-2.0
59
+ metadata:
60
+ author: gentleman-programming
61
+ version: "1.0"
62
+ ---
63
+ ```
64
+
65
+ Rules:
66
+
67
+ - `name` must be kebab-case and match the skill directory unless there is a deliberate compatibility reason.
68
+ - `description` must be one physical line, quoted, YAML-safe, and trigger-rich.
69
+ - Put essential trigger words first in `description`.
70
+ - Do not add a `Keywords` section.
71
+ - Preserve license and metadata unless the project has a stronger local convention.
72
+
73
+ ## Writing rules
74
+
75
+ - Write imperative runtime instructions, not explanatory prose.
76
+ - Keep `SKILL.md` concise: target 180–450 tokens, recommended max 700, hard max 1000.
77
+ - Prefer bullets and compact decision tables over paragraphs.
78
+ - State when to activate the skill and when not to activate it.
79
+ - Preserve author intent when improving an existing skill.
80
+ - Do not invent domain policies, triggers, or constraints. Ask or mark ambiguity instead.
81
+ - Move long examples, schemas, generated templates, and background rationale to `assets/` or `references/`.
82
+ - References must point to local files that ship with the project or package.
83
+
84
+ ## Decision gates
85
+
86
+ Use a table when choices matter:
87
+
88
+ ```markdown
89
+ | Situation | Action |
90
+ | --- | --- |
91
+ | Missing frontmatter | Fix required fields |
92
+ | Existing skill covers it | Update the existing skill instead |
93
+ | Long examples needed | Move them to `assets/` |
94
+ ```
95
+
96
+ Decision gates should prevent unsafe overreach, duplicate skills, and unnecessary ceremony.
97
+
98
+ ## Output contract
99
+
100
+ Every skill should tell the agent what to return. Good output contracts include:
101
+
102
+ - files created or modified;
103
+ - commands or verification run;
104
+ - registry refresh needed;
105
+ - unresolved ambiguities;
106
+ - residual risks.
107
+
108
+ ## Registry expectations
109
+
110
+ After creating, removing, moving, or renaming project skills, refresh the skill registry when available:
111
+
112
+ ```text
113
+ /skill-registry:refresh
114
+ ```
115
+
116
+ The registry is an index. `SKILL.md` remains the source of truth.
@@ -438,7 +438,18 @@ const SDD_AGENT_NAMES = [
438
438
  ] as const;
439
439
  const SDD_AGENT_NAME_SET = new Set<string>(SDD_AGENT_NAMES);
440
440
 
441
- type SddAgentName = (typeof SDD_AGENT_NAMES)[number];
441
+ const JUDGMENT_DAY_AGENT_NAMES = [
442
+ "jd-judge-a",
443
+ "jd-judge-b",
444
+ "jd-fix-agent",
445
+ ] as const;
446
+
447
+ const CORE_MODEL_AGENT_NAMES = [
448
+ ...SDD_AGENT_NAMES,
449
+ ...JUDGMENT_DAY_AGENT_NAMES,
450
+ ] as const;
451
+ const CORE_MODEL_AGENT_NAME_SET = new Set<string>(CORE_MODEL_AGENT_NAMES);
452
+
442
453
  type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
443
454
  interface AgentRoutingEntry {
444
455
  model?: string;
@@ -998,14 +1009,7 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
998
1009
  ];
999
1010
  const byName = new Map<string, AgentEntry>();
1000
1011
  for (const agent of agents) byName.set(agent.name, agent);
1001
- const discovered = Array.from(byName.values());
1002
- const sddFirst = SDD_AGENT_NAMES.map((name) =>
1003
- discovered.find((agent) => agent.name === name),
1004
- ).filter((agent): agent is AgentEntry => agent !== undefined);
1005
- const rest = discovered
1006
- .filter((agent) => !SDD_AGENT_NAMES.includes(agent.name as SddAgentName))
1007
- .sort((left, right) => left.name.localeCompare(right.name));
1008
- return [...sddFirst, ...rest];
1012
+ return orderDiscoverableAgents(Array.from(byName.values()));
1009
1013
  }
1010
1014
 
1011
1015
  async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
@@ -1030,14 +1034,17 @@ async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
1030
1034
  }
1031
1035
  const byName = new Map<string, AgentEntry>();
1032
1036
  for (const agent of agents) byName.set(agent.name, agent);
1033
- const discovered = Array.from(byName.values());
1034
- const sddFirst = SDD_AGENT_NAMES.map((name) =>
1035
- discovered.find((agent) => agent.name === name),
1037
+ return orderDiscoverableAgents(Array.from(byName.values()));
1038
+ }
1039
+
1040
+ function orderDiscoverableAgents(agents: AgentEntry[]): AgentEntry[] {
1041
+ const coreFirst = CORE_MODEL_AGENT_NAMES.map((name) =>
1042
+ agents.find((agent) => agent.name === name),
1036
1043
  ).filter((agent): agent is AgentEntry => agent !== undefined);
1037
- const rest = discovered
1038
- .filter((agent) => !SDD_AGENT_NAMES.includes(agent.name as SddAgentName))
1044
+ const rest = agents
1045
+ .filter((agent) => !CORE_MODEL_AGENT_NAME_SET.has(agent.name))
1039
1046
  .sort((left, right) => left.name.localeCompare(right.name));
1040
- return [...sddFirst, ...rest];
1047
+ return [...coreFirst, ...rest];
1041
1048
  }
1042
1049
 
1043
1050
  function projectSettingsPath(cwd: string): string {
@@ -1904,6 +1911,8 @@ async function applyReviewGate(
1904
1911
  export const __testing = {
1905
1912
  listAgentsFromDir,
1906
1913
  listAgentsFromDirAsync,
1914
+ listDiscoverableAgents,
1915
+ orderDiscoverableAgents,
1907
1916
  classifyGuardedCommand,
1908
1917
  loadRuntimeGuardrailsConfig,
1909
1918
  buildGentlePrompt,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gentle-pi",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -24,6 +24,7 @@
24
24
  },
25
25
  "files": [
26
26
  "assets/",
27
+ "docs/",
27
28
  "extensions/",
28
29
  "lib/",
29
30
  "prompts/",
@@ -0,0 +1,20 @@
1
+ ---
2
+ description: Create or update an LLM-first skill
3
+ argument-hint: "<skill idea or name>"
4
+ ---
5
+ Create or update an LLM-first skill for: $ARGUMENTS
6
+
7
+ Use the `skill-creator` skill if it is available. If the skill is not auto-loaded, read `skills/skill-creator/SKILL.md` and `docs/skill-style-guide.md` when present before editing.
8
+
9
+ ## Process
10
+
11
+ 1. Clarify the reusable behavior, target runtime, trigger phrases, and non-goals if they are not obvious.
12
+ 2. Inspect existing skills first; update an existing skill instead of creating a duplicate.
13
+ 3. Create or update `skills/{kebab-name}/SKILL.md` with valid one-line frontmatter description and concise runtime instructions.
14
+ 4. Put templates, schemas, or examples under `assets/`; put longer supporting docs under `references/`.
15
+ 5. If the skill is part of `gentle-pi`, update `scripts/verify-package-files.mjs`.
16
+ 6. Refresh the registry with `/skill-registry:refresh` when available, or tell the user to refresh/reload.
17
+
18
+ ## Report
19
+
20
+ Return the files changed, the selected trigger phrases, any supporting files, and whether registry/package verification remains to run.
@@ -25,6 +25,7 @@ const requiredPaths = [
25
25
  "assets/support/sdd-status-contract.md",
26
26
  "assets/support/strict-tdd.md",
27
27
  "assets/support/strict-tdd-verify.md",
28
+ "docs/skill-style-guide.md",
28
29
  "extensions/gentle-ai.ts",
29
30
  "extensions/sdd-init.ts",
30
31
  "extensions/skill-registry.ts",
@@ -33,6 +34,7 @@ const requiredPaths = [
33
34
  "prompts/gis.md",
34
35
  "prompts/gpr.md",
35
36
  "prompts/gwr.md",
37
+ "prompts/skill-creation.md",
36
38
  "skills/branch-pr/SKILL.md",
37
39
  "skills/chained-pr/SKILL.md",
38
40
  "skills/cognitive-doc-design/SKILL.md",
@@ -41,6 +43,8 @@ const requiredPaths = [
41
43
  "skills/issue-creation/SKILL.md",
42
44
  "skills/judgment-day/SKILL.md",
43
45
  "skills/release/SKILL.md",
46
+ "skills/skill-creator/SKILL.md",
47
+ "skills/skill-improver/SKILL.md",
44
48
  "skills/skill-registry/SKILL.md",
45
49
  "skills/work-unit-commits/SKILL.md",
46
50
  ];
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: judgment-day
3
- description: "Trigger: judgment day, dual review, adversarial review, juzgar. Run blind dual review, fix confirmed issues, then re-judge."
3
+ description: "Trigger: judgment day, judgement day, dual review, adversarial review, juzgar. Run blind dual review, fix confirmed issues, then re-judge."
4
4
  license: Apache-2.0
5
5
  metadata:
6
6
  author: gentleman-programming
@@ -9,7 +9,7 @@ metadata:
9
9
 
10
10
  ## Activation Contract
11
11
 
12
- Load this skill only when the user explicitly asks for Judgment Day, dual/adversarial review, or equivalent Spanish trigger (`juzgar`, `que lo juzguen`). Review a specific target: files, feature, PR, or architecture slice.
12
+ Load this skill only when the user explicitly asks for Judgment Day, Judgement Day, dual/adversarial review, or equivalent Spanish trigger (`juzgar`, `que lo juzguen`). Review a specific target: files, feature, PR, or architecture slice.
13
13
 
14
14
  ## Hard Rules
15
15
 
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: skill-creator
3
+ description: "Trigger: /skill-creation, skill creation, skill creator, create skill, new skill. Create LLM-first skills with valid frontmatter."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: gentleman-programming
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Use this skill when creating or updating a reusable AI skill for Pi or another agent runtime.
13
+
14
+ Create a skill when:
15
+ - a workflow or convention is reused across sessions;
16
+ - generic agent behavior needs project-specific constraints;
17
+ - a decision tree helps the agent choose safely;
18
+ - examples, templates, or references would make future execution more reliable.
19
+
20
+ Do not create a skill for a one-off task, generic documentation, or rules that belong in code/tests.
21
+
22
+ ## Hard Rules
23
+
24
+ - Follow `docs/skill-style-guide.md` as the normative source for skill structure and style.
25
+ - A skill is an LLM runtime contract, not human-facing docs.
26
+ - Keep `SKILL.md` concise: target 180–450 tokens, max 1000.
27
+ - Use imperative instructions and concrete gates; avoid tutorials and background prose.
28
+ - Frontmatter `description` must be one physical YAML-safe line and include trigger words first.
29
+ - Do not add a `Keywords` section; put essential trigger words in `description`.
30
+ - Put templates, schemas, and generated examples in `assets/`.
31
+ - Put longer rationale or local doc links in `references/`.
32
+ - After changing project skills, refresh the registry with `/skill-registry:refresh` when available.
33
+
34
+ ## Decision Gates
35
+
36
+ | Need | Action |
37
+ | --- | --- |
38
+ | Small reusable behavior | Create `skills/{skill-name}/SKILL.md` only |
39
+ | Templates, schemas, fixtures | Add `skills/{skill-name}/assets/` |
40
+ | Longer explanation or edge cases | Add `skills/{skill-name}/references/` |
41
+ | Existing skill covers it | Update the existing skill instead |
42
+ | Skill affects delegation discovery | Ensure trigger words appear in `description` |
43
+
44
+ ## Execution Steps
45
+
46
+ 1. Read `docs/skill-style-guide.md` before creating or updating skills.
47
+ 2. Inspect existing skills and confirm the new skill does not duplicate one.
48
+ 3. Choose a kebab-case skill name that matches the user-facing trigger.
49
+ 4. Create or update this structure:
50
+
51
+ ```text
52
+ skills/{skill-name}/
53
+ ├── SKILL.md
54
+ ├── assets/ # optional
55
+ └── references/ # optional
56
+ ```
57
+
58
+ 5. Use this frontmatter shape:
59
+
60
+ ```yaml
61
+ ---
62
+ name: {skill-name}
63
+ description: "Trigger: {phrases users or agents will say}. {What this skill does}."
64
+ license: Apache-2.0
65
+ metadata:
66
+ author: gentleman-programming
67
+ version: "1.0"
68
+ ---
69
+ ```
70
+
71
+ 6. Write sections in this order: Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References.
72
+ 7. If this is a packaged `gentle-pi` skill, add it to `scripts/verify-package-files.mjs`.
73
+ 8. Refresh or document the skill registry update path.
74
+
75
+ ## Output Contract
76
+
77
+ Return:
78
+ - Files created or modified.
79
+ - Whether this created a new skill or updated an existing one.
80
+ - Any supporting `assets/` or `references/` files added.
81
+ - Whether package verification or skill registry refresh is needed.
82
+
83
+ ## References
84
+
85
+ - `docs/skill-style-guide.md` — normative LLM-first skill style guide.
86
+ - `skills/skill-registry/SKILL.md` — registry refresh and indexing contract.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: skill-improver
3
+ description: "Trigger: improve skills, audit skills, refactor skills, skill quality. Audit and upgrade existing LLM-first skills."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: gentleman-programming
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Use this skill when auditing, refactoring, normalizing, or improving existing `SKILL.md` files. Use `skill-creator` when creating a brand-new skill from a reusable pattern.
13
+
14
+ ## Hard Rules
15
+
16
+ - Read `docs/skill-style-guide.md` first and treat it as the normative style contract.
17
+ - Treat `SKILL.md` as the source of truth; preserve author intent, critical rules, activation semantics, and output requirements.
18
+ - Use `.atl/skill-registry.md` as an index of skill names, triggers, scopes, and exact paths when available.
19
+ - Default to audit-only. Modify files only when the user explicitly asks to apply improvements.
20
+ - Never delete meaningful content silently; move long explanation, examples, templates, or schemas into local `references/` or `assets/`.
21
+ - Do not invent triggers, policies, or domain rules. Mark ambiguous cases for human review.
22
+
23
+ ## Decision Gates
24
+
25
+ | Situation | Action |
26
+ | --- | --- |
27
+ | Missing or invalid frontmatter | Fix `name`, quoted one-line `description`, `license`, and `metadata` |
28
+ | Skill reads like tutorial docs | Convert to runtime instructions and move background to `references/` |
29
+ | Body exceeds budget | Preserve rules, move examples/background to supporting files |
30
+ | Branching logic hidden in prose | Convert to a compact decision table |
31
+ | Rules conflict or intent is unclear | Report the issue; do not rewrite that rule automatically |
32
+
33
+ ## Execution Steps
34
+
35
+ 1. Read `docs/skill-style-guide.md`.
36
+ 2. Read `.atl/skill-registry.md`; use listed paths to select skills. If missing, scan known skill directories for `*/SKILL.md`.
37
+ 3. For each selected skill, audit metadata, trigger clarity, section order, body budget, actionability, decision gates, output contract, and local references.
38
+ 4. Return an audit report grouped by skill with severity and exact proposed changes.
39
+ 5. In apply mode, edit only safe issues, preserve content, create supporting files when needed, then refresh or request `/skill-registry:refresh`.
40
+
41
+ ## Output Contract
42
+
43
+ Return:
44
+ - Skills audited and paths used.
45
+ - Issues found, grouped by severity.
46
+ - Files changed, if apply mode was requested.
47
+ - Registry refresh recommendation when skill metadata or paths changed.
48
+ - Ambiguities that need human review.
49
+
50
+ ## References
51
+
52
+ - `docs/skill-style-guide.md` — normative LLM-first skill style guide.
53
+ - `skills/skill-registry/SKILL.md` — registry refresh and indexing contract.
@@ -34,3 +34,52 @@ test("agent discovery skips skills directories", async (t) => {
34
34
  ["reviewer", "worker"],
35
35
  );
36
36
  });
37
+
38
+ test("agent model discovery prioritizes SDD and Judgment Day agents", (t) => {
39
+ const root = mkdtempSync(join(tmpdir(), "gentle-pi-model-agents-"));
40
+ t.after(() => rmSync(root, { recursive: true, force: true }));
41
+ writeMarkdown(join(root, "zeta.md"), "name: zeta\n");
42
+ writeMarkdown(join(root, "jd-fix-agent.md"), "name: jd-fix-agent\n");
43
+ writeMarkdown(join(root, "sdd-apply.md"), "name: sdd-apply\n");
44
+ writeMarkdown(join(root, "alpha.md"), "name: alpha\n");
45
+ writeMarkdown(join(root, "jd-judge-b.md"), "name: jd-judge-b\n");
46
+ writeMarkdown(join(root, "sdd-init.md"), "name: sdd-init\n");
47
+ writeMarkdown(join(root, "jd-judge-a.md"), "name: jd-judge-a\n");
48
+
49
+ const discovered = __testing.listAgentsFromDir(root, "user");
50
+ const ordered = __testing.orderDiscoverableAgents(discovered);
51
+
52
+ assert.deepEqual(
53
+ ordered.map((agent) => agent.name),
54
+ [
55
+ "sdd-init",
56
+ "sdd-apply",
57
+ "jd-judge-a",
58
+ "jd-judge-b",
59
+ "jd-fix-agent",
60
+ "alpha",
61
+ "zeta",
62
+ ],
63
+ );
64
+ });
65
+
66
+ test("discoverable model agents include installed Judgment Day agents", (t) => {
67
+ const root = mkdtempSync(join(tmpdir(), "gentle-pi-installed-agents-"));
68
+ const previousHome = process.env.GENTLE_PI_AGENT_HOME;
69
+ process.env.GENTLE_PI_AGENT_HOME = root;
70
+ t.after(() => {
71
+ if (previousHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
72
+ else process.env.GENTLE_PI_AGENT_HOME = previousHome;
73
+ rmSync(root, { recursive: true, force: true });
74
+ });
75
+ writeMarkdown(join(root, "agents", "jd-judge-a.md"), "name: jd-judge-a\n");
76
+ writeMarkdown(join(root, "agents", "jd-judge-b.md"), "name: jd-judge-b\n");
77
+ writeMarkdown(join(root, "agents", "jd-fix-agent.md"), "name: jd-fix-agent\n");
78
+
79
+ const discovered = __testing.listDiscoverableAgents(root).map((agent) => agent.name);
80
+
81
+ assert.deepEqual(
82
+ discovered.filter((name) => name.startsWith("jd-")),
83
+ ["jd-judge-a", "jd-judge-b", "jd-fix-agent"],
84
+ );
85
+ });