4 +<
meta charset=
"utf-8">
5 +<
meta name=
"viewport" content=
"width=device-width, initial-scale=1">
6 +<
title>The System implementation roadmap</
title>
8 +:root {
color-scheme: light dark;
--fg:
#121212;
--bg:
#ededed;
--panel:
#dbdbdb;
--accent:
#ae2eae;
--ui:
#922792; }
9 +@media (prefers-
color-scheme:dark) { :root {
--fg:
#ededed;
--bg:
#121212;
--panel:
#242424;
--accent:
#d151d1;
--ui:
#d86dd8; } }
10 +* {
box-sizing:
border-box; }
11 +body {
margin:
0;
background:
var(
--bg);
color:
var(
--fg);
font:
14px/
1.5 ui-monospace,
SFMono-Regular,
Consolas,
monospace; }
12 +article {
width:min(
100% -
2rem,
980px);
margin:
1rem auto 3rem;
border:
3px solid var(
--fg);
box-shadow:
9px 9px 0 var(
--ui); }
13 +header,
section {
padding:clamp(
1rem,
3vw,
1.5rem);
border-bottom:
2px solid var(
--fg); }
14 +header {
background:
var(
--panel);
border-bottom-width:
3px; }
15 +h1 {
margin:
.2rem 0 0;
font:
900 clamp(
1.8rem,
6vw,
3.5rem)/.95
system-ui;
text-transform:
uppercase; }
16 +h2 {
margin:
0 0 1rem;
color:
var(
--accent);
font:
900 1rem/
1 system-ui;
letter-spacing:
.1em;
text-transform:
uppercase; }
17 +h3 {
margin:
1rem 0 .4rem;
font-size:
.9rem;
text-transform:
uppercase; }
18 +p,
li {
max-width:
82ch; }
19 +.phase {
border-left:
8px solid var(
--ui); }
20 +.phase
strong {
color:
var(
--accent); }
21 +code {
background:
var(
--panel);
padding:
.1rem .3rem; }
22 +a {
color:
var(
--accent);
font-weight:
900; }
23 +@media(
max-width:
600px) {
article {
width:
calc(
100% - 1rem);
margin:
.5rem;
box-shadow:
5px 5px 0 var(
--ui); } }
29 +<
p><
strong>Implementation roadmap · 2026-07-11</
strong></
p>
31 +<
p><
a href=
"../specs/2026-07-11-the-system-design.html">Design spec</
a></
p>
32 +<
p>Eight independently green phases keep the hard rename, governance kernel, document workflows, and final integration reviewable.</
p>
35 +<
section class=
"phase">
36 +<
h2>Phase 1 · Hard rename baseline</
h2>
37 +<
p><
strong>Outcome:</
strong> all existing Super behavior ships under <
code>the-system</
code> only.</
p>
40 +<
li>Rename extension directory, package, branding, imports, tests, root resources, lockfile entries, static checks, TypeScript config, README rows, and current examples.</
li>
41 +<
li>Preserve task branches, push-task, mockup, renderer, and existing skills without semantic changes.</
li>
42 +<
li>Add a scoped static assertion rejecting live old paths while allowing historical <
code>docs/super/**</
code>.</
li>
44 +<
h3>Out of scope</
h3>
45 +<
p>Governance, HTML documents, prompts, and new skills.</
p>
46 +<
h3>Verification</
h3>
47 +<
p>Renamed focused tests, real Pi harness loading, typecheck, static checks, and full CI.</
p>
49 +<
p>The repository remains functionally identical except for the intentional hard public rename.</
p>
52 +<
section class=
"phase">
53 +<
h2>Phase 2 · Project and document kernel</
h2>
54 +<
p><
strong>Outcome:</
strong> a dormant, pure, tested model understands project roots, config, IDs, metadata, document relationships, and the shared stylesheet.</
p>
57 +<
li>Add <
code>documents.ts</
code> with native JJ/Git worktree root discovery and conflict detection.</
li>
58 +<
li>Add normalized governed-path containment.</
li>
59 +<
li>Define strict config, prefix, ID, slug, filename, and metadata schemas.</
li>
60 +<
li>Index authored documents and report stable diagnostics for duplicate IDs, filename mismatch, dangling references, and forbidden graph edges.</
li>
61 +<
li>Validate the narrow authored HTML shell and obvious active-resource violations without executing content.</
li>
62 +<
li>Add the approved versioned Nugu <
code>assets/system.css</
code>.</
li>
64 +<
h3>Out of scope</
h3>
65 +<
p>Runtime hooks and filesystem mutation.</
p>
66 +<
h3>Verification</
h3>
67 +<
p>Table-driven unit tests for simple Git, Git worktrees, JJ, colocated/conflicting roots, no VCS, config, IDs, metadata, graph rules, HTML, and CSS tokens.</
p>
69 +<
p>New code is unused by runtime; existing extension behavior remains unchanged and CI-green.</
p>
72 +<
section class=
"phase">
73 +<
h2>Phase 3 · Doctor vertical slice</
h2>
74 +<
p><
strong>Outcome:</
strong> users can inspect any project system without mutation.</
p>
77 +<
li>Add deterministic read-only doctor script using the Phase 2 kernel.</
li>
78 +<
li>Add <
code>system-doctor</
code> skill and thin <
code>/system-doctor</
code> prompt.</
li>
79 +<
li>Add initial <
code>system-documents</
code> skill as the single document-authoring authority.</
li>
80 +<
li>Export package prompts and update exact resource/static checks.</
li>
82 +<
h3>Out of scope</
h3>
83 +<
p>Initialization, injection, and write gates.</
p>
84 +<
h3>Verification</
h3>
85 +<
p>Fixture-tree diagnostics, stable ordering, exit status, no-mutation proof, skill contracts, and real package resource discovery.</
p>
87 +<
p>Doctor is independently useful while all existing runtime behavior remains intact.</
p>
90 +<
section class=
"phase">
91 +<
h2>Phase 4 · Guided initialization</
h2>
92 +<
p><
strong>Outcome:</
strong> <
code>/system-init</
code> creates or upgrades a valid project system through explicit human decisions.</
p>
95 +<
li>Add thin prompt and <
code>the-system-init</
code> skill.</
li>
96 +<
li>Inspect project context and grill one focused question at a time.</
li>
97 +<
li>Draft and separately approve missing core Markdown files.</
li>
98 +<
li>Create directories/config and copy bundled CSS.</
li>
99 +<
li>Make reruns idempotent, core-preserving, and explicit about machine-asset upgrades.</
li>
100 +<
li>Validate through doctor after writes.</
li>
102 +<
h3>Out of scope</
h3>
103 +<
p>Automatic runtime injection or write interception.</
p>
104 +<
h3>Verification</
h3>
105 +<
p>Skill contract tests, config/CSS copy checks, missing/existing core behavior, prefix handling, and repeat-run fixtures.</
p>
107 +<
p>Initialization works as an on-demand agent workflow; the extension still does not alter normal turns.</
p>
110 +<
section class=
"phase">
111 +<
h2>Phase 5 · Runtime governance</
h2>
112 +<
p><
strong>Outcome:</
strong> initialized projects inject their laws and receive advisory ownership protection.</
p>
115 +<
li>Add <
code>system.ts</
code> runtime orchestration.</
li>
116 +<
li>Resolve root per turn and inject bounded existing SYSTEM/MISSION/RULES in stable order.</
li>
117 +<
li>Notify once per session when initialization or version refresh is needed.</
li>
118 +<
li>Block edits to existing core files.</
li>
119 +<
li>Allow new specs and mockups; require UI approval for edits to existing spec-owned files.</
li>
120 +<
li>Preflight write/edit candidates with shared validation.</
li>
121 +<
li>Conservatively guard recognizable shell mutations and state the advisory boundary.</
li>
123 +<
h3>Out of scope</
h3>
124 +<
p>Workflow output migration.</
p>
125 +<
h3>Verification</
h3>
126 +<
p>Real event shapes, injection composition, root changes, UI approve/deny/cancel, no-UI failure, candidate validation, and retained task/mockup tests.</
p>
128 +<
p>Existing task workflows still function; initialized projects gain coherent governance without hidden repair.</
p>
131 +<
section class=
"phase">
132 +<
h2>Phase 6 · Spec authoring and browser review</
h2>
133 +<
p><
strong>Outcome:</
strong> brainstorming produces validated brutal HTML specs and separately editable spec-owned mockups.</
p>
136 +<
li>Migrate brainstorming through <
code>system-documents</
code>.</
li>
137 +<
li>Add thin <
code>/system-spec</
code> prompt.</
li>
138 +<
li>Allocate spec IDs and write semantic HTML linked to shared CSS.</
li>
139 +<
li>Persist only accepted mockups as adjacent compliant assets.</
li>
140 +<
li>Add cross-platform shell-free browser opener script.</
li>
141 +<
li>Print source path and ask before opening; never auto-open browser/editor.</
li>
143 +<
h3>Out of scope</
h3>
144 +<
p>Roadmaps, plans, implementation, and issues.</
p>
145 +<
h3>Verification</
h3>
146 +<
p>Workflow contracts, generated fixtures, approval behavior, mockup ownership, opener argv/platform tests, and generic mockup regressions.</
p>
148 +<
p>An approved idea can complete the full design/spec review loop while later lifecycle stages remain on existing behavior.</
p>
151 +<
section class=
"phase">
152 +<
h2>Phase 7 · Roadmap, plan, and implementation lifecycle</
h2>
153 +<
p><
strong>Outcome:</
strong> approved specs move through HTML roadmaps/plans into execution by PLAN-ID.</
p>
156 +<
li>Migrate writing-roadmaps and writing-plans to validated HTML, exact metadata, and project-local paths.</
li>
157 +<
li>Add <
code>/system-roadmap</
code>, <
code>/system-plan</
code>, and <
code>/system-impl</
code> prompts.</
li>
158 +<
li>Update reviewer prompts and downstream skills to read HTML.</
li>
159 +<
li>Resolve plans by ID and execute one spec or one roadmap phase with existing checkpoints.</
li>
161 +<
h3>Out of scope</
h3>
162 +<
p>Issue capture.</
p>
163 +<
h3>Verification</
h3>
164 +<
p>Prompt delegation, metadata/reference fixtures, phase boundary tests, plan execution resolution, report-only review, and full workflow-skill tests.</
p>
166 +<
p>The primary spec-driven development lifecycle is complete and CI-green.</
p>
169 +<
section class=
"phase">
170 +<
h2>Phase 8 · Issue memory and integration hardening</
h2>
171 +<
p><
strong>Outcome:</
strong> defect capture completes the system and every spec contract is verified.</
p>
174 +<
li>Add general-purpose <
code>system-issues</
code> skill and <
code>/system-issue</
code> prompt.</
li>
175 +<
li>Support empty spec references while the violated contract is unknown; preserve deduplication and sanitized evidence.</
li>
176 +<
li>Complete startup, doctor, graph, approval, resource discovery, rename, and package integration tests.</
li>
177 +<
li>Update final current documentation and changelog.</
li>
178 +<
li>Run final typecheck, focused suites, real extension loading, static checks, and CI.</
li>
180 +<
h3>Out of scope</
h3>
181 +<
p>Provider-specific research, Git sync, compatibility aliases, and historical document migration.</
p>
182 +<
h3>Verification</
h3>
183 +<
p>Issue workflow fixtures, complete behavioral-contract audit against the spec, no live old-path references outside the historical allowlist, and <
code>mise run ci</
code>.</
p>
185 +<
p>The full design is implemented under one public extension with no half-migration or legacy surface.</
p>