repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): add guided init workflow

41b0ccd8a95f5fa0b288bc0a979dd5dc48e0994e

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

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

Modified
69 69 assert.match(reviewing, /Risky new code/);
72 + it("keeps system-init prompt thin and its argument unapproved", () => {
73 + const template = prompt("system-init");
74 + assert.match(template, /^---\ndescription: Initialize or upgrade The System through guided approval\nargument-hint: "\[PROJECT-PREFIX\]"\n---/);
75 + assert.match(template, /the-system-init skill/);
76 + assert.match(template, /\$ARGUMENTS/);
77 + assert.match(template, /proposal, not approval/);
78 + assert.doesNotMatch(template, /config\.json|system\.css|SYSTEM\.md|MISSION\.md|RULES\.md|mkdir|writeFile/);
79 + });
81 + it("defines root-aware approval-bound core-preserving initialization", () => {
82 + const init = skill("the-system-init");
83 + for (const contract of [
84 + "privileged instructions", "README", "agent instructions", "build files",
85 + "one focused question at a time", "purpose", "audience", "non-goals",
86 + "engineering constraints", "security", "data", "tests", "release expectations",
87 + "[A-Z][A-Z0-9]{1,7}", "scripts/init.mjs inspect", "scripts/init.mjs apply",
88 + "scripts/init.mjs upgrade", "Never overwrite an existing core file",
89 + "Approve writing .system/MISSION.md?", "Approve writing .system/RULES.md?",
90 + "Approve writing .system/SYSTEM.md?", "scripts/doctor.mjs",
91 + ]) assert.ok(init.includes(contract), `missing init contract: ${contract}`);
92 + for (const file of ["MISSION.md", "RULES.md", "SYSTEM.md"])
93 + assert.ok(init.indexOf(`Approve writing .system/${file}?`) < init.indexOf(`Write .system/${file}`));
94 + assert.match(init, /Never launch a browser or editor/);
95 + });
72 97 it("keeps system-doctor prompt thin and delegates without repair", () => {
73 98 const template = prompt("system-doctor");
74 99 const doctor = skill("system-doctor");
112 - it("discovers doctor resources from both package manifests", async () => {
137 + it("discovers phase resources from both package manifests", async () => {
113 138 const sandbox = mkdtempSync(path.join(tmpdir(), "the-system-resources-"));
115 140 const settings = SettingsManager.create(
141 166 assert.deepEqual(relativeResources(root, extension.prompts), [
142 167 "prompts/system-doctor.md",
168 + "prompts/system-init.md",
144 - assert.ok(
145 - relativeResources(root, extension.skills).includes(
146 - "skills/system-doctor/SKILL.md",
147 - ),
148 - );
149 - assert.ok(
150 - relativeResources(
151 - path.resolve(root, "../.."),
152 - repository.prompts,
153 - ).includes("extensions/the-system/prompts/system-doctor.md"),
154 - );
170 + for (const expected of ["skills/system-doctor/SKILL.md", "skills/the-system-init/SKILL.md"])
171 + assert.ok(relativeResources(root, extension.skills).includes(expected));
172 + const repositoryPrompts = relativeResources(path.resolve(root, "../.."), repository.prompts);
173 + for (const expected of [
174 + "extensions/the-system/prompts/system-doctor.md",
175 + "extensions/the-system/prompts/system-init.md",
176 + ]) assert.ok(repositoryPrompts.includes(expected));
155 177 } finally {
156 178 rmSync(sandbox, { recursive: true, force: true });

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

Added
new file mode 100644
1 +---
2 +description: Initialize or upgrade The System through guided approval
3 +argument-hint: "[PROJECT-PREFIX]"
4 +---
6 +Use the the-system-init skill for the current project.
7 +Treat optional prefix `$ARGUMENTS` as a proposal, not approval, and follow every focused question and separate write decision in the skill.

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

Added
new file mode 100644
1 +---
2 +name: the-system-init
3 +description: Create or upgrade a project-local .system through focused questions and explicit human approvals
4 +---
6 +# The System Init
8 +Use only for an explicit initialization or upgrade request; never during normal turns.
10 +## Safety
12 +Before any write, explain that `.system/SYSTEM.md`, `.system/MISSION.md`, and `.system/RULES.md` are privileged instructions future agents may receive as authority.
13 +Tell the user not to place secrets, credentials, raw private data, or binary bytes in them.
14 +Preserve unrelated dirty work.
15 +Never overwrite an existing core file.
16 +Never silently repair malformed config, root conflict, prefix conflict, newer project version, or unsafe path.
17 +Resolve `../../scripts/init.mjs` and `../../scripts/doctor.mjs` against this skill directory.
18 +Use absolute paths with `node --no-warnings --experimental-strip-types`.
20 +## Inspect
22 +Use `scripts/init.mjs inspect`:
23 +`node --no-warnings --experimental-strip-types <absolute-init-path> inspect <current-cwd>`.
24 +Pass a command prefix only as a proposal, not approval.
25 +Report every `ROOT`, `PREFIX`, `CORE`, `CREATE`, and `UPGRADE` line; stop on `ERROR`.
26 +Read existing `.system`, README/purpose docs, agent instructions, package/language manifests, build files, task config, conventional tests, top-level structure, and security/data/release config without mutation.
27 +Summarize facts, conflicts, and unknowns; never ask the user to repeat a consistent inspected fact.
29 +## Interview
31 +For first initialization or missing core truth, ask one focused question at a time and wait.
32 +Cover unresolved topics in order: purpose/outcome; audience/operators; non-goals/boundaries; engineering constraints/environments; security/trust; data ownership/retention/privacy/migration; tests/verification; release expectations/compatibility/rollout/rollback.
33 +Challenge vagueness or conflict with one follow-up at a time.
34 +When all cores exist on rerun, preserve settled truth and ask only about a machine upgrade or explicit requested gap.
36 +## Prefix and machine assets
38 +Propose one prefix from prompt argument, repository name, package name, or title, in that order.
39 +Require `[A-Z][A-Z0-9]{1,7}` and ask `Approve project prefix PREFIX?`.
40 +Only explicit yes approves; otherwise request one replacement, validate, and ask again.
41 +Existing config prefix is authoritative; stop rather than change a conflict.
42 +After approval, use `scripts/init.mjs apply`:
43 +`node --no-warnings --experimental-strip-types <absolute-init-path> apply <root> <approved-prefix>`.
44 +Relay every `WROTE` and `PENDING` line.
45 +If pending, display every config transition and CSS replacement, then ask `Approve the reported machine-owned config/CSS upgrade?`.
46 +On yes, use `scripts/init.mjs upgrade`:
47 +`node --no-warnings --experimental-strip-types <absolute-init-path> upgrade <root> <approved-prefix>`.
48 +On no, preserve assets, state doctor remains non-green, and do not claim completion.
50 +## Separate core approvals
52 +Use inspected facts and answers; never invent an unanswered rule.
53 +Do not modify, reformat, or seek blanket reapproval for a `preserve` core.
54 +For missing mission, show the whole project-specific draft with `# Mission`, `## Purpose`, `## Audience`, `## Outcomes`, and `## Non-goals`.
55 +Ask exactly: `Approve writing .system/MISSION.md?`
56 +Revise and redisplay when requested.
57 +Write .system/MISSION.md only after explicit approval of that displayed draft.
58 +For missing rules, show the whole project-specific draft with `# Rules`, `## Engineering constraints`, `## Security and data`, `## Testing`, and `## Release`.
59 +Ask exactly: `Approve writing .system/RULES.md?`
60 +Revise and redisplay when requested.
61 +Write .system/RULES.md only after explicit approval of that displayed draft.
62 +For missing topology, show this complete canonical draft without project facts:
64 +```markdown
65 +# The System
67 +## Authority
69 +MISSION.md defines why this project exists.
70 +RULES.md defines how work must be done.
71 +Approved specs define what behavior must exist.
72 +Metadata is the authority for system-document relationships.
74 +## Ownership
76 +Humans own SYSTEM.md, MISSION.md, RULES.md, specs, and accepted spec-owned mockups.
77 +Agents may draft roadmaps and plans for human review and maintain issues and research.
78 +Machine-owned config.json and system.css change only through initialization.
80 +## Documents
82 +Authored documents are editable HTML in matching .system directories.
83 +Each uses ../system.css and exactly one system-meta JSON block.
84 +Specs are leaf truth.
85 +Roadmaps reference one spec; plans reference one spec and optionally one matching roadmap phase; issues reference violated specs.
86 +Tests use SYSTEM-SPEC comments.
87 +Accepted mockups live beside and belong to their spec.
89 +## Safety
91 +System documents contain no secrets, credentials, raw private data, or binary asset bytes.
92 +Invalid or outdated state is reported and never silently repaired.
93 +```
95 +Ask exactly: `Approve writing .system/SYSTEM.md?`
96 +Revise and redisplay when requested.
97 +Write .system/SYSTEM.md only after explicit approval of that displayed draft.
98 +Denied approval leaves the core absent and initialization incomplete.
100 +## Validate
102 +Use `scripts/doctor.mjs` after approved writes:
103 +`node --no-warnings --experimental-strip-types <absolute-doctor-path> <root>`.
104 +Preserve report order; never hide or automatically repair findings.
105 +Exit 0 with `OK The System is valid` means completion; exit 1 means incomplete or invalid.
106 +Report root, prefix, created machine paths, preserved/new cores, upgrade decision, and doctor status.
107 +Never launch a browser or editor.
108 +Do not commit unless separately asked.