repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): add doctor and document skills

81af8f41c317207d073cd435e9a3357ff1169600

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

extensions/the-system/__tests__/workflow-skills.test.ts

Modified
6 6 const root = path.resolve(import.meta.dirname, "..");
7 7 const skill = (name: string) =>
8 8 readFileSync(path.join(root, "skills", name, "SKILL.md"), "utf8");
9 +const prompt = (name: string) =>
10 + readFileSync(path.join(root, "prompts", `${name}.md`), "utf8");
10 12 describe("the-system workflow phase skills", () => {
11 13 it("offers spec prototyping after approved risky specs and before planning", () => {
61 63 assert.match(reviewing, /New APIs/);
62 64 assert.match(reviewing, /Risky new code/);
67 + it("keeps system-doctor prompt thin and delegates without repair", () => {
68 + const template = prompt("system-doctor");
69 + const doctor = skill("system-doctor");
71 + assert.match(template, /^---\ndescription: Diagnose The System without mutation\n---/);
72 + assert.match(template, /system-doctor skill/);
73 + assert.doesNotMatch(template, /config\.json|system\.css|readdir|writeFile/);
74 + assert.match(doctor, /\.\.\/\.\.\/scripts\/doctor\.mjs/);
75 + assert.match(doctor, /--experimental-strip-types/);
76 + assert.match(doctor, /Exit 0/);
77 + assert.match(doctor, /Exit 1/);
78 + assert.match(doctor, /Never edit, initialize, upgrade, copy, or delete/);
79 + });
81 + it("makes system-documents the single authored-document authority", () => {
82 + const documents = skill("system-documents");
84 + for (const contract of [
85 + "single document-authoring authority",
86 + "../system.css",
87 + "system-meta",
88 + "SPEC|ROADMAP|PLAN|ISSUE|RESEARCH",
89 + "Metadata is the reference authority",
90 + "spec-owned mockup",
91 + "Never open a browser or editor automatically",
92 + "scripts/doctor.mjs",
93 + ])
94 + assert.ok(documents.includes(contract), `missing document contract: ${contract}`);
95 + assert.doesNotMatch(documents, /initialize|SYSTEM\.md|MISSION\.md|RULES\.md/i);
96 + });

extensions/the-system/prompts/system-doctor.md

Added
new file mode 100644
1 +---
2 +description: Diagnose The System without mutation
3 +---
4 +Use the system-doctor skill to run deterministic validation for the current project and explain every reported line without changing files.

extensions/the-system/skills/system-doctor/SKILL.md

Added
new file mode 100644
1 +---
2 +name: system-doctor
3 +description: Diagnose a project's .system tree deterministically without changing files
4 +---
6 +# System Doctor
8 +Use this skill when a user asks to inspect, validate, or explain a project system.
10 +## Run
12 +1. Resolve `../../scripts/doctor.mjs` against this skill directory and use that absolute path.
13 +2. Run `node --no-warnings --experimental-strip-types <absolute-doctor-path> <project-cwd>`.
14 +3. Treat `ROOT`, `REF`, `ERROR`, and `OK` as the complete machine report.
16 +Exit 0 means the project system is valid.
17 +Exit 1 means one or more findings were reported.
19 +## Explain
21 +- Preserve report order.
22 +- Explain each code, path, observed state, and required human action.
23 +- State that discovered `REF` lines are informational unless a matching dangling-reference error exists.
24 +- State that active-markup checks are structural lint, not browser sandboxing.
25 +- Never edit, initialize, upgrade, copy, or delete project files.
26 +- Never rerun with a repair flag; no repair mode exists.

extensions/the-system/skills/system-documents/SKILL.md

Added
new file mode 100644
1 +---
2 +name: system-documents
3 +description: Apply The System HTML, metadata, ID, reference, mockup, validation, and browser-review contracts
4 +---
6 +# System Documents
8 +This is the single document-authoring authority for `.system` authored documents.
9 +Other lifecycle skills must delegate these rules instead of copying or weakening them.
11 +## Preconditions
13 +- Discover the project root from the nearest `.jj` and `.git` markers; stop when they disagree.
14 +- Read `.system/config.json`; require its approved prefix and current schema/style versions.
15 +- Resolve every target below the project root and reject traversal.
16 +- Inspect existing filenames and metadata before allocating an ID.
18 +## IDs and paths
20 +Use `<PREFIX>-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-<SEQUENCE>`.
21 +Start sequence text at three digits, permit growth past 999, and use the next unused value for that type.
22 +Use lowercase ASCII slugs matching `[a-z0-9]+(?:-[a-z0-9]+)*`.
23 +Write `<ID>-<slug>.html` only in its matching `.system/specs|roadmaps|plans|issues|research` directory.
25 +## HTML source
27 +Every authored document is complete, formatted, directly editable HTML with:
29 +- `<!doctype html>`, `<html lang="en">`, UTF-8 charset, viewport, and a nonempty title;
30 +- exactly one `<link rel="stylesheet" href="../system.css">`;
31 +- header followed by main containing one section;
32 +- semantic headings, paragraphs, lists, tables, asides, figures, and details where appropriate;
33 +- one readable `<script type="application/json" id="system-meta">` block.
35 +Inline CSS may express document-specific layout but may not redefine shared Nugu colors, typography, breakpoints, or components.
36 +Inline JavaScript must be optional, dependency-free progressive disclosure, filtering, or a tiny explanation.
37 +Forbid network APIs, browser storage, dynamic import, external scripts, event-handler attributes, executable URL schemes, iframes, objects, embeds, meta refresh, remote runtime assets, generated SVG sludge, and diagram libraries.
38 +HTTPS anchors remain allowed navigation.
40 +## Metadata and graph
42 +Metadata is the reference authority; prose links never create graph edges.
43 +Use exact keys only:
45 +- spec: `id`, `type`;
46 +- roadmap: `id`, `type`, one `spec`;
47 +- plan: `id`, `type`, one `spec`, plus `roadmap` and positive `phase` together when phase-scoped;
48 +- issue: `id`, `type`, `open|fixed` status, unique `specs` array;
49 +- research: `id`, `type`, ISO `capturedAt`, optional unique HTTPS `sources`.
51 +Specs are leaf truth and have no outgoing system-document metadata.
52 +Roadmaps point to one spec.
53 +Plans point to one spec and optionally one phase of a roadmap for that same spec.
54 +Issues point only to specs; an empty array is allowed while the violated contract is unknown.
55 +Tests use a language-appropriate `SYSTEM-SPEC: <SPEC-ID>` comment.
57 +## Spec-owned mockups
59 +Persist only a human-accepted spec-owned mockup.
60 +Place it beside its owner as `<spec-stem>-mockup-<option-slug>.html` and link it relatively from the spec.
61 +A mockup is a constituent asset, not an authored graph node: do not add `system-meta`.
62 +Keep it standalone, editable, dependency-free, and subject to the same active-resource prohibitions.
64 +## Validate and review
66 +After writing or materially editing a document, run the bundled `../../scripts/doctor.mjs` through Node with `--experimental-strip-types`.
67 +Do not hide, reorder, or silently repair findings.
68 +Print the exact source path and ask whether browser review is wanted.
69 +Never open a browser or editor automatically.
70 +Only use an explicitly approved, shell-free local-file opener when one is available; otherwise leave the source path as the review interface.