archik 0.19.5 → 0.20.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/.claude-plugin/marketplace.json +2 -2
- package/.claude-plugin/plugin.json +1 -5
- package/README.md +23 -28
- package/commands/accept.md +7 -47
- package/commands/bootstrap.md +25 -28
- package/commands/evolve.md +12 -50
- package/commands/migrate.md +35 -59
- package/commands/self-evolving.md +6 -6
- package/commands/spawn.md +10 -37
- package/commands/suggest.md +0 -42
- package/dist/cli/archik.mjs +453 -585
- package/dist/ui/assets/index-Bn3qR7Cx.js +223 -0
- package/dist/ui/assets/index-DUgLHSFs.css +1 -0
- package/dist/ui/index.html +2 -2
- package/docs/templates/CLAUDE.md +55 -148
- package/docs/templates/principles/functional.md +2 -3
- package/docs/templates/principles/oop.md +3 -4
- package/docs/templates/superpowers.md +4 -4
- package/package.json +1 -7
- package/skills/archik/SKILL.md +19 -304
- package/commands/actor.md +0 -89
- package/commands/alpha.md +0 -73
- package/commands/trace.md +0 -57
- package/commands/usecase.md +0 -134
- package/dist/trace.d.ts +0 -18
- package/dist/trace.js +0 -58
- package/dist/ui/assets/index-BrvxaIkh.css +0 -1
- package/dist/ui/assets/index-C1kLj8Cy.js +0 -226
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-rotate-x:initial;--tw-rotate-y:initial;--tw-rotate-z:initial;--tw-skew-x:initial;--tw-skew-y:initial;--tw-border-style:solid;--tw-font-weight:initial;--tw-tracking:initial;--tw-shadow:0 0 #0000;--tw-shadow-color:initial;--tw-shadow-alpha:100%;--tw-inset-shadow:0 0 #0000;--tw-inset-shadow-color:initial;--tw-inset-shadow-alpha:100%;--tw-ring-color:initial;--tw-ring-shadow:0 0 #0000;--tw-inset-ring-color:initial;--tw-inset-ring-shadow:0 0 #0000;--tw-ring-inset:initial;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-offset-shadow:0 0 #0000;--tw-outline-style:solid;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial}}}@layer theme{:root,:host{--font-sans:ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--color-rose-700:oklch(51.4% .222 16.935);--spacing:.25rem;--container-3xl:48rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--font-weight-semibold:600;--tracking-tight:-.025em;--radius-md:.375rem;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono)}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring{outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab,red,red)){::placeholder{color:color-mix(in oklab,currentcolor 50%,transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.collapse{visibility:collapse}.invisible{visibility:hidden}.visible{visibility:visible}.absolute{position:absolute}.fixed{position:fixed}.relative{position:relative}.static{position:static}.sticky{position:sticky}.start{inset-inline-start:var(--spacing)}.end{inset-inline-end:var(--spacing)}.z-50{z-index:50}.container{width:100%}@media(min-width:40rem){.container{max-width:40rem}}@media(min-width:48rem){.container{max-width:48rem}}@media(min-width:64rem){.container{max-width:64rem}}@media(min-width:80rem){.container{max-width:80rem}}@media(min-width:96rem){.container{max-width:96rem}}.mt-1{margin-top:calc(var(--spacing) * 1)}.mt-auto{margin-top:auto}.ml-auto{margin-left:auto}.block{display:block}.contents{display:contents}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.inline-block{display:inline-block}.inline-flex{display:inline-flex}.table{display:table}.h-full{height:100%}.min-h-0{min-height:calc(var(--spacing) * 0)}.w-72{width:calc(var(--spacing) * 72)}.w-full{width:100%}.max-w-3xl{max-width:var(--container-3xl)}.flex-1{flex:1}.grow{flex-grow:1}.transform{transform:var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,)}.resize{resize:both}.grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.flex-col{flex-direction:column}.items-baseline{align-items:baseline}.items-center{align-items:center}.justify-center{justify-content:center}.gap-2{gap:calc(var(--spacing) * 2)}.gap-3{gap:calc(var(--spacing) * 3)}.gap-4{gap:calc(var(--spacing) * 4)}.truncate{text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.overflow-hidden{overflow:hidden}.overflow-y-auto{overflow-y:auto}.rounded{border-radius:.25rem}.rounded-md{border-radius:var(--radius-md)}.border{border-style:var(--tw-border-style);border-width:1px}.p-1{padding:calc(var(--spacing) * 1)}.p-2{padding:calc(var(--spacing) * 2)}.p-4{padding:calc(var(--spacing) * 4)}.p-6{padding:calc(var(--spacing) * 6)}.px-2{padding-inline:calc(var(--spacing) * 2)}.px-4{padding-inline:calc(var(--spacing) * 4)}.py-1\.5{padding-block:calc(var(--spacing) * 1.5)}.py-2\.5{padding-block:calc(var(--spacing) * 2.5)}.pt-2{padding-top:calc(var(--spacing) * 2)}.pt-4{padding-top:calc(var(--spacing) * 4)}.text-center{text-align:center}.text-left{text-align:left}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-tight{--tw-tracking:var(--tracking-tight);letter-spacing:var(--tracking-tight)}.whitespace-pre-wrap{white-space:pre-wrap}.text-rose-700{color:var(--color-rose-700)}.lowercase{text-transform:lowercase}.uppercase{text-transform:uppercase}.italic{font-style:italic}.underline{text-decoration-line:underline}.shadow{--tw-shadow:0 1px 3px 0 var(--tw-shadow-color,#0000001a), 0 1px 2px -1px var(--tw-shadow-color,#0000001a);box-shadow:var(--tw-inset-shadow),var(--tw-inset-ring-shadow),var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow)}.outline{outline-style:var(--tw-outline-style);outline-width:1px}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.filter{filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to,opacity,box-shadow,transform,translate,scale,rotate,filter,-webkit-backdrop-filter,backdrop-filter,display,content-visibility,overlay,pointer-events;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}@media(hover:hover){.hover\:no-underline:hover{text-decoration-line:none}}}:root,[data-theme=light]{--archik-canvas:#f8fafc;--archik-panel:#fff;--archik-surface:#f1f5f9;--archik-surface-hover:#e2e8f0;--archik-fg:#0f172a;--archik-fg-dim:#475569;--archik-fg-muted:#94a3b8;--archik-border:#e2e8f0;--archik-border-strong:#cbd5e1;--archik-accent:#2563eb;--archik-accent-bright:#3b82f6;--archik-magenta:#db2777;--archik-success:#10b981;--archik-warning:#d97706;--archik-danger:#e11d48;--archik-node-fill:#fff;--archik-node-fill-tinted:#f1f5f9;--archik-node-fill-frame:#fff;--archik-node-stroke:#0f172a;--archik-node-stroke-soft:#475569;--archik-container-border:#94a3b8;--archik-node-text:#0f172a;--archik-node-text-dim:#475569;--archik-node-caption:#64748b;--archik-node-chrome-dot:#cbd5f5;--archik-edge-filled:#0f172a;--archik-edge-open:#334155;--archik-edge-dim:#64748b;--archik-edge-async:#2563eb;--archik-grid-minor:#e2e8f0;--archik-grid-major:#cbd5e1;--archik-selected:#2563eb;--archik-selected-glow:#2563eb2e;--archik-status-proposed:#6366f1;--archik-status-deprecated:#d97706;color-scheme:light}[data-theme=dark]{--archik-canvas:#000;--archik-panel:#0a0a0a;--archik-surface:#161616;--archik-surface-hover:#222;--archik-fg:#fff;--archik-fg-dim:#c8c8c8;--archik-fg-muted:#9a9a9a;--archik-border:#262626;--archik-border-strong:#3d3d3d;--archik-accent:#22d3ee;--archik-accent-bright:#67e8f9;--archik-magenta:#f472b6;--archik-success:#34d399;--archik-warning:#fbbf24;--archik-danger:#fb7185;--archik-node-fill:#0c0c0c;--archik-node-fill-tinted:#181818;--archik-node-fill-frame:#101010;--archik-node-stroke:#3d3d3d;--archik-node-stroke-soft:#2a2a2a;--archik-container-border:#4a4a4a;--archik-node-text:#fff;--archik-node-text-dim:#d6d6d6;--archik-node-caption:#67e8f9;--archik-node-chrome-dot:#3a3a3a;--archik-edge-filled:#ededed;--archik-edge-open:#b0b0b0;--archik-edge-dim:#7a7a7a;--archik-edge-async:#67e8f9;--archik-grid-minor:#0f0f0f;--archik-grid-major:#1c1c1c;--archik-selected:#22d3ee;--archik-selected-glow:#22d3ee47;--archik-status-proposed:#818cf8;--archik-status-deprecated:#fbbf24;color-scheme:dark}html,body,#root{background:var(--archik-canvas);height:100%;color:var(--archik-fg);-webkit-font-smoothing:antialiased;margin:0;font-family:Inter,system-ui,sans-serif}.archik-panel{background:var(--archik-panel);border:1px solid var(--archik-border);border-radius:8px}.archik-input{background:var(--archik-surface);color:var(--archik-fg);border:1px solid var(--archik-border);font:inherit;border-radius:4px;outline:none;padding:4px 8px;font-size:12px;transition:border-color .12s,box-shadow .12s}.archik-input:focus{border-color:var(--archik-accent);box-shadow:0 0 0 3px var(--archik-selected-glow)}.archik-btn{background:var(--archik-surface);color:var(--archik-fg);border:1px solid var(--archik-border);cursor:pointer;border-radius:4px;align-items:center;gap:4px;padding:5px 10px;font-size:12px;font-weight:500;transition:background .12s,border-color .12s,color .12s;display:inline-flex}.archik-btn:hover{background:var(--archik-surface-hover);border-color:var(--archik-border-strong)}.archik-btn:disabled{opacity:.5;cursor:not-allowed}.archik-focus-step{width:22px;height:22px;color:var(--archik-fg-dim);cursor:pointer;background:0 0;border:none;border-radius:5px;justify-content:center;align-items:center;padding:0;transition:background .12s,color .12s;display:inline-flex}.archik-focus-step:hover:not(:disabled){background:var(--archik-accent)}@supports (color:color-mix(in lab,red,red)){.archik-focus-step:hover:not(:disabled){background:color-mix(in srgb,var(--archik-accent) 22%,transparent)}}.archik-focus-step:hover:not(:disabled){color:var(--archik-accent)}.archik-focus-step:focus-visible{outline:2px solid var(--archik-accent);outline-offset:1px}.archik-focus-step:disabled{opacity:.4;cursor:not-allowed}.archik-btn-primary{background:var(--archik-accent);border-color:var(--archik-accent);color:#000}.archik-btn-primary:hover{background:var(--archik-accent-bright);border-color:var(--archik-accent-bright)}[data-theme=light] .archik-btn-primary{color:#fff}.archik-btn-danger{color:var(--archik-danger);border-color:var(--archik-danger);background:0 0;border-style:dashed}.archik-btn-danger:hover{background:var(--archik-danger);color:#000;border-style:solid}.archik-pill{letter-spacing:.02em;border:1px solid #0000;border-radius:999px;align-items:center;gap:4px;padding:2px 8px;font-size:11px;display:inline-flex}.archik-pill--info{color:var(--archik-accent);border-color:var(--archik-border-strong);background:var(--archik-accent)}@supports (color:color-mix(in lab,red,red)){.archik-pill--info{background:color-mix(in oklab,var(--archik-accent) 8%,transparent)}}.archik-pill--success{color:var(--archik-success);background:var(--archik-success)}@supports (color:color-mix(in lab,red,red)){.archik-pill--success{background:color-mix(in oklab,var(--archik-success) 12%,transparent)}}.archik-pill--warning{color:var(--archik-warning);background:var(--archik-warning)}@supports (color:color-mix(in lab,red,red)){.archik-pill--warning{background:color-mix(in oklab,var(--archik-warning) 14%,transparent)}}.archik-pill--danger{color:var(--archik-danger);background:var(--archik-danger)}@supports (color:color-mix(in lab,red,red)){.archik-pill--danger{background:color-mix(in oklab,var(--archik-danger) 14%,transparent)}}.archik-label{letter-spacing:.12em;text-transform:uppercase;color:var(--archik-fg-muted);margin-bottom:4px;font-size:10px;display:block}.archik-mono{color:var(--archik-fg);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px}.archik-divider{border-top:1px solid var(--archik-border)}.archik-grid{background-color:var(--archik-canvas);background-image:radial-gradient(var(--archik-grid-minor) 1px,transparent 1px),radial-gradient(var(--archik-grid-major) 1px,transparent 1px);background-position:0 0,0 0;background-size:20px 20px,100px 100px}.archik-selected-glow{filter:drop-shadow(0 0 6px var(--archik-selected-glow)) drop-shadow(0 0 2px var(--archik-selected-glow));animation:1.8s ease-in-out infinite archikPulse}[data-archik-node-id][data-archik-status=proposed]{opacity:.82}[data-archik-node-id][data-archik-status=proposed] rect,[data-archik-node-id][data-archik-status=proposed] path,[data-archik-node-id][data-archik-status=proposed] ellipse,[data-archik-node-id][data-archik-status=proposed] line{stroke:var(--archik-status-proposed);stroke-dasharray:5 3}[data-archik-node-id][data-archik-status=deprecated]{opacity:.7}[data-archik-node-id][data-archik-status=deprecated] rect,[data-archik-node-id][data-archik-status=deprecated] path,[data-archik-node-id][data-archik-status=deprecated] ellipse,[data-archik-node-id][data-archik-status=deprecated] line{stroke:var(--archik-status-deprecated);stroke-dasharray:2 4}[data-archik-node-id][data-archik-status=deprecated] text{text-decoration:line-through;text-decoration-thickness:1px;-webkit-text-decoration-color:var(--archik-status-deprecated);text-decoration-color:var(--archik-status-deprecated)}@keyframes archikPulse{0%,to{filter:drop-shadow(0 0 4px var(--archik-selected-glow)) drop-shadow(0 0 1px var(--archik-selected-glow))}50%{filter:drop-shadow(0 0 12px var(--archik-selected-glow)) drop-shadow(0 0 3px var(--archik-selected-glow))}}.archik-modal-overlay{z-index:50;background:var(--archik-canvas);justify-content:center;align-items:center;display:flex;position:fixed;inset:0}@supports (color:color-mix(in lab,red,red)){.archik-modal-overlay{background:color-mix(in oklab,var(--archik-canvas) 70%,transparent)}}.archik-modal-overlay{-webkit-backdrop-filter:blur(4px);animation:.14s ease-out archikFadeIn}.archik-modal{background:var(--archik-panel);border:1px solid var(--archik-border);width:360px;max-width:calc(100vw - 32px);box-shadow:0 12px 40px #00000059,0 0 0 1px var(--archik-border-strong);border-radius:8px;padding:16px;animation:.2s cubic-bezier(.2,.8,.2,1) archikModalIn}.archik-selected-outline{fill:none;stroke:var(--archik-selected);stroke-width:2px;pointer-events:none}@keyframes archikEdgeFlow{0%{stroke-dashoffset:0}to{stroke-dashoffset:calc(-1 * var(--archik-dash-period,8) * 1px)}}.archik-edge-flowing{animation:1.4s linear infinite archikEdgeFlow}@media(prefers-reduced-motion:reduce){.archik-edge-flowing{animation:none}}.archik-popover{background:var(--archik-panel);border:1px solid var(--archik-border-strong);border-radius:6px;flex-direction:column;max-height:min(80vh,600px);padding:4px;animation:.16s cubic-bezier(.2,.8,.2,1) archikModalIn;display:flex;overflow:hidden;box-shadow:0 12px 32px #00000059}.archik-menu-item{width:100%;color:var(--archik-fg);cursor:pointer;text-align:left;background:0 0;border:0;border-radius:4px;align-items:center;gap:8px;padding:6px 10px;font-size:12px;display:flex}.archik-menu-item:hover{background:var(--archik-surface-hover)}.archik-menu-item--danger{color:var(--archik-danger)}@keyframes archikFadeIn{0%{opacity:0}to{opacity:1}}@keyframes archikModalIn{0%{opacity:0;transform:translateY(8px)scale(.98)}to{opacity:1;transform:none}}.archik-drawer-shell{flex-direction:column;min-width:0;transition:width .22s cubic-bezier(.2,.8,.2,1),opacity .2s,margin-left .22s cubic-bezier(.2,.8,.2,1);display:flex;overflow:hidden}.archik-drawer-shell--open{opacity:1;width:320px;margin-left:16px}.archik-drawer-shell--closed{opacity:0;pointer-events:none;width:0;margin-left:0}.archik-drawer-content{flex-shrink:0;width:320px;height:100%}.archik-drawer-fade{animation:.22s ease-out archikFadeIn}.archik-zoom-btn{min-width:28px;height:24px;padding:0 8px}.archik-sheet-handle{flex-shrink:0;justify-content:center;align-items:center;padding:10px 12px 2px;display:none;position:relative}.archik-sheet-grip{background:var(--archik-border-strong);border-radius:2px;width:36px;height:4px}.archik-sheet-close{width:32px;height:32px;color:var(--archik-fg-dim);cursor:pointer;background:0 0;border:none;border-radius:6px;justify-content:center;align-items:center;font-size:13px;display:flex;position:absolute;top:2px;right:8px}.archik-sheet-close:hover{background:var(--archik-surface-hover);color:var(--archik-fg)}@media(max-width:768px){.archik-main{padding:0!important}.archik-main>.archik-panel{border:0;border-radius:0}.archik-drawer-shell{z-index:40;margin-left:0;transition:transform .22s cubic-bezier(.2,.8,.2,1),opacity .2s;position:fixed;bottom:0;left:0;right:0}.archik-drawer-shell--open{width:auto;margin-left:0;transform:translateY(0)}.archik-drawer-shell--closed{width:auto;margin-left:0;transform:translateY(100%)}.archik-drawer-content{border-bottom:0;border-radius:14px 14px 0 0;flex-direction:column;width:100%;height:60dvh;display:flex}.archik-drawer-content>:not(.archik-sheet-handle){flex:1;min-height:0;height:auto!important}.archik-sheet-handle{display:flex}}@media(pointer:coarse){.archik-btn{min-height:36px;padding:8px 12px}.archik-zoom-btn{min-width:40px;height:40px;padding:0 10px}.archik-focus-step{width:32px;height:32px}}@property --tw-rotate-x{syntax:"*";inherits:false}@property --tw-rotate-y{syntax:"*";inherits:false}@property --tw-rotate-z{syntax:"*";inherits:false}@property --tw-skew-x{syntax:"*";inherits:false}@property --tw-skew-y{syntax:"*";inherits:false}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@property --tw-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-shadow-color{syntax:"*";inherits:false}@property --tw-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-inset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-shadow-color{syntax:"*";inherits:false}@property --tw-inset-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-ring-color{syntax:"*";inherits:false}@property --tw-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-ring-color{syntax:"*";inherits:false}@property --tw-inset-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-ring-inset{syntax:"*";inherits:false}@property --tw-ring-offset-width{syntax:"<length>";inherits:false;initial-value:0}@property --tw-ring-offset-color{syntax:"*";inherits:false;initial-value:#fff}@property --tw-ring-offset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-outline-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}
|
package/dist/ui/index.html
CHANGED
|
@@ -14,8 +14,8 @@
|
|
|
14
14
|
}
|
|
15
15
|
} catch {}
|
|
16
16
|
</script>
|
|
17
|
-
<script type="module" crossorigin src="/assets/index-
|
|
18
|
-
<link rel="stylesheet" crossorigin href="/assets/index-
|
|
17
|
+
<script type="module" crossorigin src="/assets/index-Bn3qR7Cx.js"></script>
|
|
18
|
+
<link rel="stylesheet" crossorigin href="/assets/index-DUgLHSFs.css">
|
|
19
19
|
</head>
|
|
20
20
|
<body>
|
|
21
21
|
<div id="root"></div>
|
package/docs/templates/CLAUDE.md
CHANGED
|
@@ -2,18 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
> Drop this file into any new project as `CLAUDE.md`. Then your very first message to me should be **`/archik:bootstrap`** — I'll detect what state the project is in (empty, has-code, already-modelled) and route to the right next step. If you already know what you want to build, you can append a one-line brief: `/archik:bootstrap <what you're building>`. I'll then run the loop below.
|
|
4
4
|
>
|
|
5
|
-
> **Framing that makes the rest of the loop work:** when I ask for your brief, end it with *"start by modelling the
|
|
5
|
+
> **Framing that makes the rest of the loop work:** when I ask for your brief, end it with *"start by modelling the smallest structure for the first thing I should ship."* That single line forces priorities into the open before any code lands — pick exactly one (no "I might also want…"), and "to ship" (new nodes start `proposed` and flip to `active` when their code lands in BUILD).
|
|
6
6
|
|
|
7
7
|
## How I work on this project
|
|
8
8
|
|
|
9
|
-
I move from **brief →
|
|
9
|
+
I move from **brief → structural model → build plan → code**. Each step is a reviewable artifact, gated by a HITL accept before the next one is produced. If implementation invalidates the model, I stop coding and fix the model first.
|
|
10
10
|
|
|
11
|
-
The **
|
|
11
|
+
The **structural model** (archik diagram — nodes, nesting via `parentId` and sub-files, edges) says *what exists* and *which way dependencies flow*. `archik drift` and `archik smells` check it against the real code. Code is the last artifact, not the first.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Two gate types:
|
|
14
14
|
|
|
15
|
-
- **
|
|
16
|
-
- **Canvas gate** — `/archik:accept` on the rendered diff. Used only for the structural sidecar.
|
|
15
|
+
- **Canvas gate** — `/archik:accept` on the rendered diff. Used for the structural sidecar.
|
|
17
16
|
- **Plan gate** — user replies "approve". Used for the build plan before any code edits.
|
|
18
17
|
|
|
19
18
|
### Match ritual to scope
|
|
@@ -21,46 +20,40 @@ Three gate types, one per artifact class:
|
|
|
21
20
|
Not every task needs the full loop. Skip the modeling phases and just edit when the change is:
|
|
22
21
|
|
|
23
22
|
- A single-file script, a one-line config tweak, a typo / copy fix
|
|
24
|
-
- A pure refactor that doesn't change the component graph or any
|
|
23
|
+
- A pure refactor that doesn't change the component graph or any user-visible behavior
|
|
25
24
|
- A bug fix inside an existing node that doesn't change its responsibility
|
|
26
25
|
|
|
27
|
-
Run the loop when the change introduces new behavior, a new structural shape, a new external interaction
|
|
26
|
+
Run the loop when the change introduces new behavior, a new structural shape, or a new external interaction.
|
|
28
27
|
|
|
29
28
|
### The five-phase loop
|
|
30
29
|
|
|
31
|
-
**DISCOVER → DESIGN → DECIDE → BUILD → VERIFY**, with one critical back-edge: if BUILD reveals
|
|
30
|
+
**DISCOVER → DESIGN → DECIDE → BUILD → VERIFY**, with one critical back-edge: if BUILD reveals the model is wrong, stop coding and loop back to DESIGN.
|
|
32
31
|
|
|
33
|
-
- **DISCOVER** — `npx archik q stats / list
|
|
34
|
-
- **DESIGN** —
|
|
35
|
-
- **DECIDE** — `/archik:accept` on the structural sidecar
|
|
32
|
+
- **DISCOVER** — `npx archik q stats / list`, `npx archik smells`, `ls` source dirs. Read before write.
|
|
33
|
+
- **DESIGN** — structural sidecar with rationale (boundaries, nesting, dependency direction).
|
|
34
|
+
- **DECIDE** — `/archik:accept` on the structural sidecar.
|
|
36
35
|
- **BUILD** — numbered plan → "approve" → execute in small commits. Tests-first when the behavior is clearly bounded.
|
|
37
|
-
- **VERIFY** — validate, tests, lint, build, `archik
|
|
36
|
+
- **VERIFY** — validate, tests, lint, build, `archik drift`, `archik smells`, eyeball UI. Stage the `proposed → active` flip.
|
|
38
37
|
|
|
39
38
|
The **per-milestone rhythm** below is the actionable checklist that walks these phases step-by-step.
|
|
40
39
|
|
|
41
|
-
### Worked example — one
|
|
40
|
+
### Worked example — one feature end-to-end
|
|
42
41
|
|
|
43
42
|
User says: *"add password reset by email."*
|
|
44
43
|
|
|
45
44
|
I'd run the loop like this:
|
|
46
45
|
|
|
47
|
-
1. **DISCOVER** — `npx archik q
|
|
46
|
+
1. **DISCOVER** — `npx archik q list`, `npx archik q describe auth-service`, peek at `src/auth/`. Find that an `auth-service` node already handles login.
|
|
48
47
|
|
|
49
|
-
2. **DESIGN (
|
|
48
|
+
2. **DESIGN** — `npx archik suggest set` adding two `proposed` nodes under the `auth` module: a `reset-handler` and an `email-sender` that talks to the email provider (modelled as `external`). Two new edges: `reset-handler → email-sender (calls)`, `reset-handler → auth-service (writes)`. Dependencies flow one way — nothing in `auth-service` imports the handler. Wait for **`/archik:accept`** on the canvas.
|
|
50
49
|
|
|
51
|
-
3. **
|
|
50
|
+
3. **BUILD plan** — `src/auth/resetHandler.ts` (request + verify), `src/auth/emailSender.ts` (provider client), `tests/auth/reset.happy.spec.ts`, `tests/auth/reset.expired.spec.ts`. Each new edge maps to a real call. Out of scope: rate limiting (next milestone). Wait for "approve".
|
|
52
51
|
|
|
53
|
-
4. **
|
|
52
|
+
4. **Execute** — small commits. One per file roughly.
|
|
54
53
|
|
|
55
|
-
5. **
|
|
54
|
+
5. **VERIFY** — tests pass; `npx archik drift` is clean; `npx archik smells` shows no new folder loop. Stage a sidecar flipping the two new nodes from `proposed → active` with `sourcePath`. Hand off.
|
|
56
55
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
7. **Execute** — small commits. One per file roughly.
|
|
60
|
-
|
|
61
|
-
8. **VERIFY** — tests pass; `npx archik trace` shows `reset-password/happy ✓` and `reset-password/expired-token ✓`. Stage a sidecar flipping the two new nodes from `proposed → active` with `sourcePath`. Hand off.
|
|
62
|
-
|
|
63
|
-
The whole flow produces five reviewable artifacts before code lands. Each is small. None is optional once the loop applies.
|
|
56
|
+
The flow produces two reviewable artifacts (diagram, plan) before code lands. Each is small. Neither is optional once the loop applies.
|
|
64
57
|
|
|
65
58
|
## First message — project brief
|
|
66
59
|
|
|
@@ -71,137 +64,68 @@ The recommended opener is **`/archik:bootstrap`** (with or without an inline bri
|
|
|
71
64
|
npx archik@latest init # fresh project — creates .archik/main.archik.yaml + slash commands
|
|
72
65
|
npx archik upgrade # already installed — pulls latest, refreshes SKILL.md + slash commands
|
|
73
66
|
```
|
|
74
|
-
Either path leaves the slash commands (`/archik:suggest`, `/archik:accept`, `/archik:
|
|
67
|
+
Either path leaves the slash commands (`/archik:suggest`, `/archik:accept`, `/archik:evolve`, etc.) and the live canvas (`npx archik dev`) in place.
|
|
75
68
|
|
|
76
|
-
2. **Read the current state** with `ls -F`, `npx archik q list
|
|
69
|
+
2. **Read the current state** with `ls -F`, `npx archik q list` (only relevant if archik is already populated), and `npx archik smells` (when code exists).
|
|
77
70
|
|
|
78
71
|
3. **Surface genuine ambiguities** — usually 2–4 questions about scope, target users, hard constraints, or non-obvious tradeoffs. Skip questions whose answers are in the brief.
|
|
79
72
|
|
|
80
|
-
4. **
|
|
81
|
-
|
|
82
|
-
5. **Author the use cases** (direct-write) — what the actors want to accomplish. One `*.archik.uc.yaml` per use case under `.archik/usecases/`. Each includes a basic flow, alternate flows, and slices (a slice = a flow subset + the test paths that prove it). Active slices must name test files that will exist on disk when the code lands. Run `npx archik validate`. Show inline and wait for confirmation.
|
|
83
|
-
|
|
84
|
-
6. **Stage the structural model** via `npx archik suggest set` — every node the finished system needs, marked `status: proposed`, parented to a top-level `module`. Nodes participating in use case flows carry `stereotype: boundary | control | entity`. Wait for **`/archik:accept`** on the canvas (formal gate).
|
|
85
|
-
|
|
86
|
-
7. **Author the behavioral model** (direct-write) — one `.archik.seq.yaml` per slice that has a non-trivial runtime flow. Each seq file carries a `realizes: { useCase, slice }` block so the validator enforces bidirectional integrity. Participants bind to architecture node ids. Run `npx archik validate`. Show inline and wait for confirmation.
|
|
73
|
+
4. **Stage the structural model** via `npx archik suggest set` — every node the finished system needs, marked `status: proposed`, parented to a top-level `module`. Wait for **`/archik:accept`** on the canvas (formal gate).
|
|
87
74
|
|
|
88
|
-
|
|
75
|
+
5. **The whole architecture lives on day one as `proposed`.** Milestones flip subsets from `proposed` to `active` (with `sourcePath`) as code lands. The set of nodes a milestone flips IS the milestone.
|
|
89
76
|
|
|
90
77
|
## Per-milestone rhythm
|
|
91
78
|
|
|
92
|
-
Every milestone follows the same shape.
|
|
79
|
+
Every milestone follows the same shape. Two gate types apply — **canvas gate** (`/archik:accept`) and **plan gate** ("approve"):
|
|
93
80
|
|
|
94
|
-
1. **
|
|
95
|
-
2.
|
|
96
|
-
3. **
|
|
97
|
-
4.
|
|
98
|
-
5. **
|
|
99
|
-
6. **
|
|
100
|
-
7. **
|
|
101
|
-
8. **
|
|
102
|
-
9. **
|
|
103
|
-
10. **Stage the `proposed → active` sidecar** — `/archik:suggest "flip <list> to active"`. Flips nodes/edges/slices with their `sourcePath` and `tests` now on disk.
|
|
104
|
-
11. **Hand off** — list what to eyeball; wait for `/archik:accept` and (if there's a deploy) confirm deploy is green. Then `/archik:alpha show` and promote any alpha whose criteria are now met.
|
|
105
|
-
12. **Commit + push** — only after the user confirms.
|
|
106
|
-
|
|
107
|
-
### When to author a sequence diagram
|
|
108
|
-
|
|
109
|
-
Author one when the milestone slice introduces:
|
|
110
|
-
|
|
111
|
-
- **Branching** — auth flows, conditional routing, retries with fallback.
|
|
112
|
-
- **Async fan-out** — one event triggers multiple subscribers.
|
|
113
|
-
- **Cross-context interaction** — three or more nodes participate in a single user-visible action.
|
|
114
|
-
- **External integrations with non-trivial handshake** — OAuth, webhook callbacks, idempotent retries.
|
|
115
|
-
- **Anything the user explicitly wants to spec before code** — even if it would otherwise be trivial.
|
|
116
|
-
|
|
117
|
-
Skip when: a single node handles the request end-to-end with no branching, or the slice is already covered by an existing seq file.
|
|
81
|
+
1. **Structural sidecar** — `/archik:suggest <feature>`. Stages the proposed end-state for this milestone via `npx archik suggest set` under the hood. Rationale in 2–4 bullets.
|
|
82
|
+
2. **`/archik:accept` on the structural diagram** — formal canvas gate.
|
|
83
|
+
3. **BUILD plan** — one-line goal, deps, files with paths and signatures, non-obvious bits, acceptance gate, out-of-scope items, the `proposed → active` flip this milestone will produce. Each new edge must map to a real call in the plan.
|
|
84
|
+
4. **"approve" on the plan** — plan gate. Don't start editing files until approved.
|
|
85
|
+
5. **Execute** — small commits, narrate non-obvious decisions, declare back-edges to DESIGN openly when they happen.
|
|
86
|
+
6. **Verify** — project tests → lint → build → `npx archik drift` → `npx archik smells` → aesthetic eyeball (if UI). No new folder loop should close the milestone.
|
|
87
|
+
7. **Stage the `proposed → active` sidecar** — `/archik:suggest "flip <list> to active"`. Flips nodes/edges with their `sourcePath` now on disk.
|
|
88
|
+
8. **Hand off** — list what to eyeball; wait for `/archik:accept` and (if there's a deploy) confirm deploy is green.
|
|
89
|
+
9. **Commit + push** — only after the user confirms.
|
|
118
90
|
|
|
119
91
|
## Hard rules
|
|
120
92
|
|
|
121
|
-
1. **
|
|
122
|
-
2. **
|
|
123
|
-
3. **
|
|
124
|
-
4. **
|
|
125
|
-
5. **
|
|
126
|
-
6. **
|
|
127
|
-
7. **
|
|
128
|
-
8. **
|
|
129
|
-
9. **Back-edge from BUILD lands on whichever model is wrong.** If implementation reveals the structural model is wrong, fix the structural sidecar. If it reveals the behavioral model is wrong, edit the seq file. If it reveals the use case is wrong, update the uc file. Never paper over.
|
|
130
|
-
10. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
|
|
93
|
+
1. **Structure → plan → code. In that order.** The accepted diagram defines what to build. Code lands last.
|
|
94
|
+
2. **Two gate types.** The structural model gets a **canvas gate** (`/archik:accept`). The build plan gets an **approval gate** ("approve"). Don't conflate them — `/archik:accept` only works on structural sidecars.
|
|
95
|
+
3. **Dependencies flow one way.** Sibling folders must not import each other. `npx archik smells` reports folder loops with the real imports as evidence — fix them, don't invent labels for them.
|
|
96
|
+
4. **Stop at every milestone boundary.** Summarize what shipped, run verifications (`archik drift` and `archik smells`), ask for the visual ack before continuing.
|
|
97
|
+
5. **Boring underneath.** No experimental framework features unless explicitly requested. Match the stack the brief specifies.
|
|
98
|
+
6. **No scope creep.** Out-of-scope items go in `FUTURE.md`, not the current milestone.
|
|
99
|
+
7. **Back-edge from BUILD lands on the model.** If implementation reveals the structural model is wrong, fix it with a fresh sidecar. Never paper over.
|
|
100
|
+
8. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
|
|
131
101
|
|
|
132
102
|
## What each phase produces
|
|
133
103
|
|
|
134
104
|
### DISCOVER
|
|
135
105
|
- `npx archik q stats` and `npx archik q list` to ground in the current diagram.
|
|
136
|
-
- `npx archik
|
|
137
|
-
- `npx archik q sequences` to see flows already modelled.
|
|
106
|
+
- `npx archik smells` to see folder loops and oversized files in the code.
|
|
138
107
|
- `ls -F` of relevant source dirs.
|
|
139
108
|
- A mental map of what exists vs what the request needs.
|
|
140
109
|
- No code, no diagram changes yet.
|
|
141
110
|
|
|
142
|
-
### DESIGN
|
|
143
|
-
- One file: `*.archik.actors.yaml`. Separates human actors from system integrations.
|
|
144
|
-
- `kind: human | external-system | time | device`.
|
|
145
|
-
- Each actor has an `id`, a `description`, and optional `goals` (free text).
|
|
146
|
-
- Direct-write — no sidecar workflow. Validate with `npx archik validate`.
|
|
147
|
-
|
|
148
|
-
### DESIGN — (b) Requirements (use cases + slices)
|
|
149
|
-
- One `*.archik.uc.yaml` per use case under `.archik/usecases/`.
|
|
150
|
-
- Required fields: `id`, `name`, `primaryActor` (resolves in the actor index), `flows.basic`, at least one slice.
|
|
151
|
-
- Each slice: `id`, `description`, `flows` (which flows it covers), `tests` (array of on-disk test paths).
|
|
152
|
-
- Active slices with missing test files fail validation — same discipline as `sourcePath`.
|
|
153
|
-
- Optional: `realization.seqFile` per slice (set after the seq diagram is written).
|
|
154
|
-
- Schema: `npx archik schema uc`.
|
|
155
|
-
|
|
156
|
-
### DESIGN — (c) Structural
|
|
111
|
+
### DESIGN
|
|
157
112
|
- One-line intent.
|
|
158
113
|
- 1–3 clarifying questions only when there's genuine ambiguity.
|
|
159
114
|
- A sidecar staged via `npx archik suggest set --note "..."` containing the **full proposed end-state**.
|
|
160
115
|
- New code-bearing nodes use `status: proposed` and may omit `sourcePath`.
|
|
161
|
-
-
|
|
116
|
+
- Containers via `parentId`; a big subsystem gets its own sub-file via `archikFile`.
|
|
162
117
|
- `description` on every node explains *what it does*, not *what kind it is*.
|
|
163
118
|
- Bounded contexts named explicitly; cross-context calls default to async unless there's a reason.
|
|
164
119
|
- Public traffic routes through a `gateway`/`auth` node, not directly to a service.
|
|
165
120
|
|
|
166
|
-
**ECB completeness check** — before staging the sidecar, run through
|
|
167
|
-
each active use case slice and verify the structural model has all
|
|
168
|
-
three ECB roles covered (each must carry the matching `stereotype`
|
|
169
|
-
field):
|
|
170
|
-
- A **boundary** node (`stereotype: boundary`) — the entry point the
|
|
171
|
-
actor touches: API handler, gateway, BFF. Missing = the slice has
|
|
172
|
-
no identified entry point; the actor has nowhere to call.
|
|
173
|
-
- A **control** node (`stereotype: control`) — the orchestrator that
|
|
174
|
-
runs the use case logic: service, use-case handler, workflow engine.
|
|
175
|
-
Missing = logic will bleed into the boundary or entity.
|
|
176
|
-
- An **entity** node (`stereotype: entity`) — persistent state:
|
|
177
|
-
repository, domain model, DB-backed store. Missing for a
|
|
178
|
-
state-changing slice = the persistence concern is unmodelled.
|
|
179
|
-
|
|
180
|
-
If any ECB role is absent, add the missing node (`status: proposed`
|
|
181
|
-
if not yet built) and tag it with the correct `stereotype` before
|
|
182
|
-
staging. An incomplete ECB model at structural-design time produces
|
|
183
|
-
ECB rule violations when the seq diagram is validated.
|
|
184
|
-
|
|
185
|
-
### DESIGN — (d) Behavioral
|
|
186
|
-
- One `.archik.seq.yaml` per non-trivial slice.
|
|
187
|
-
- Carries `realizes: { useCase: <id>, slice: <id> }` at the top level.
|
|
188
|
-
- Participants bound to architecture node ids that exist in the structural model.
|
|
189
|
-
- Messages typed correctly: `sync` / `async` / `return` / `create` / `destroy`.
|
|
190
|
-
- Branches modelled with `alt` / `opt` / `loop` groups; large flows via `ref` groups.
|
|
191
|
-
- `npx archik validate` run after every write — catches broken `nodeId` refs, duplicate step ids, and ECB rule violations.
|
|
192
|
-
- Linked from the relevant architecture node via `seqFiles` (this part goes through the structural sidecar).
|
|
193
|
-
|
|
194
121
|
### DECIDE
|
|
195
122
|
- The user runs `/archik:accept` (apply) or `/archik:reject` (with a reason).
|
|
196
123
|
- On reject: ask one specific question pinned to one axis — boundary / relationship / scope / naming / composition / lifecycle. Treat the answer as a hard constraint, re-stage. Never silently retry the same draft.
|
|
197
|
-
- Each model is its own gate.
|
|
198
124
|
|
|
199
125
|
### BUILD
|
|
200
126
|
- A numbered file-level plan, presented before any edit:
|
|
201
127
|
- Each new code-bearing node → its `sourcePath` and the concrete files / signatures.
|
|
202
128
|
- Each new edge that requires code → the corresponding code change.
|
|
203
|
-
- Each accepted seq diagram → trace it: every message in the flow must map to a function call in the plan.
|
|
204
|
-
- Slice test paths declared in the use case → scaffold those test files.
|
|
205
129
|
- Default to **tests-first** when the behavior is clearly bounded.
|
|
206
130
|
- Out-of-scope items called out explicitly.
|
|
207
131
|
- Wait for "approve" before editing.
|
|
@@ -211,61 +135,44 @@ ECB rule violations when the seq diagram is validated.
|
|
|
211
135
|
1. Project tests — all passing.
|
|
212
136
|
2. Lint — clean.
|
|
213
137
|
3. Build / typecheck — clean.
|
|
214
|
-
4. `npx archik validate` — schema + cross-file +
|
|
215
|
-
5. `npx archik
|
|
216
|
-
6. `npx archik
|
|
138
|
+
4. `npx archik validate` — schema + cross-file + constraint checks clean.
|
|
139
|
+
5. `npx archik drift` — structural model matches disk.
|
|
140
|
+
6. `npx archik smells` — no new folder loops or oversized files. `--fail-on-warn` for CI gates.
|
|
217
141
|
7. Aesthetic eyeball when there's a UI — share a screenshot, ask before declaring done.
|
|
218
142
|
8. Stage the `proposed → active` sidecar — flip nodes/edges with `sourcePath`.
|
|
219
|
-
9.
|
|
220
|
-
10. Commit (with a Co-Authored-By line) and push — only after user confirms.
|
|
143
|
+
9. Commit (with a Co-Authored-By line) and push — only after user confirms.
|
|
221
144
|
|
|
222
145
|
## Archik commands I use
|
|
223
146
|
|
|
224
147
|
**Reading the models:**
|
|
225
148
|
- `npx archik q list | edges | describe <id> | dependents <id> | impact <id>` — structural model.
|
|
226
|
-
- `npx archik q sequences [--node <id>]` — seq flows.
|
|
227
149
|
- `npx archik q stats` — node + edge counts.
|
|
228
|
-
- `npx archik
|
|
229
|
-
- `npx archik q describe-usecase <id>` — one use case in detail.
|
|
230
|
-
- `npx archik q actors` — actor index.
|
|
150
|
+
- `npx archik affected [--since <ref>]` — changed files → nodes and their dependents.
|
|
231
151
|
|
|
232
152
|
**Authoring:**
|
|
233
153
|
- `npx archik schema` — once before authoring any sidecar.
|
|
234
|
-
- `npx archik schema uc` — use case schema.
|
|
235
|
-
- `npx archik schema actors` — actors schema.
|
|
236
154
|
- `npx archik suggest set --note "<one-liner>" - <<'YAML' ... YAML` — stage a structural sidecar (full document).
|
|
237
|
-
- Direct `Write` / `Edit` on `*.archik.actors.yaml`, `*.archik.uc.yaml`, `*.archik.seq.yaml` — these have no sidecar workflow.
|
|
238
155
|
|
|
239
156
|
**Lifecycle:**
|
|
240
157
|
- `npx archik suggest accept | reject | show` — structural sidecar lifecycle.
|
|
241
|
-
- `npx archik validate` — schema + cross-file +
|
|
242
|
-
- `npx archik trace [--json] [--fail-on partial|none]` — coverage matrix: use case × slice × test × seq × ECB.
|
|
243
|
-
- `npx archik alpha show` — alpha state snapshot with verification badges.
|
|
244
|
-
- `npx archik alpha promote <alpha> <state> [--note <text>]` — promote with machine-checkable gate.
|
|
158
|
+
- `npx archik validate` — schema + cross-file + constraint checks.
|
|
245
159
|
|
|
246
160
|
**Verification & rendering:**
|
|
247
161
|
- `npx archik drift` — source paths that no longer exist on disk.
|
|
162
|
+
- `npx archik smells [--fail-on-warn]` — folder import loops + oversized files, with import evidence.
|
|
248
163
|
- `npx archik render --out docs/architecture.svg` — regenerate committed SVG.
|
|
249
|
-
- `npx archik render --seq <path> --out <file>` — render a seq diagram to SVG.
|
|
250
164
|
|
|
251
165
|
## Common pitfalls
|
|
252
166
|
|
|
253
167
|
- **Editing `.archik/main.archik.yaml` by hand** — forbidden; always go through `suggest set`.
|
|
254
|
-
- **Skipping actors before use cases** — actors must exist before use cases can reference `primaryActor`.
|
|
255
|
-
- **Active slices without on-disk test paths** — validator rejects them. Use `status: proposed` for slices whose tests aren't written yet.
|
|
256
|
-
- **Seq file missing `realizes` block** — when a slice declares `realization.seqFile`, that seq file must carry the matching `realizes` block. The validator checks both directions.
|
|
257
|
-
- **Seq participants missing the `seqFiles` backref on the architecture node** — when you write a `realizes`-bound seq, every architecture node listed as a participant must also declare that seq in its own `seqFiles` array. Otherwise the seq is "linked from the requirements side, orphaned from the structural side" — `archik validate` rejects it. When staging the structural sidecar that hosts the participants, add `seqFiles: [.archik/<flow>.archik.seq.yaml]` to each. Closes the third side of the integrity triangle (use case ↔ seq ↔ node).
|
|
258
|
-
- **ECB violations in realized seq diagrams** — actor → boundary → control → entity is the allowed chain. `npx archik validate` catches violations at error level.
|
|
259
|
-
- **Skipping the behavioral model when the slice has branching or async** — write the seq diagram; future Claude reads it.
|
|
260
168
|
- **Writing prose-only summaries instead of staging a sidecar** — every structural change must produce a reviewable artifact.
|
|
261
|
-
- **Skipping the BUILD-plan HITL** —
|
|
262
|
-
- **Renaming an `id` mid-flow** — forbidden; remove the old and add a new one. Renames break diff
|
|
263
|
-
- **
|
|
264
|
-
- **Over-claiming an alpha state** — `archik alpha show` marks it `✗ over-claimed`. Either fix the artifacts or demote the state.
|
|
169
|
+
- **Skipping the BUILD-plan HITL** — diagram acceptance is not implicit code approval.
|
|
170
|
+
- **Renaming an `id` mid-flow** — forbidden; remove the old and add a new one. Renames break diff and require manual re-link in code.
|
|
171
|
+
- **Labelling a smell without evidence** — name a folder loop by the imports `archik smells` shows, not by a made-up category.
|
|
265
172
|
|
|
266
173
|
## Working with this file
|
|
267
174
|
|
|
268
175
|
- This is `CLAUDE.md`. Future Claude sessions read it first.
|
|
269
176
|
- I add an `@AGENTS.md` line at the top if the project has framework-specific agent rules.
|
|
270
177
|
- I add project-specific sections under `## Stack` and `## File / module layout` once the architecture stabilizes — they replace the generic guidance with concrete file paths.
|
|
271
|
-
-
|
|
178
|
+
- Three artifacts, one project: this file is the **rhythm**, the archik diagram is the **structural model**, the code is the **implementation**. The rhythm threads them together.
|
|
@@ -36,9 +36,8 @@ shaped*.
|
|
|
36
36
|
## Side effects at the edges
|
|
37
37
|
|
|
38
38
|
- Push effects (I/O, network, DB, randomness, time) to the boundary of the
|
|
39
|
-
system; keep the interior pure.
|
|
40
|
-
|
|
41
|
-
orchestration, **entity** code is pure data + transitions.
|
|
39
|
+
system; keep the interior pure. Edge code performs effects, the core
|
|
40
|
+
is pure orchestration, and data modules are pure data + transitions.
|
|
42
41
|
- Make effects explicit and injected — pass the clock, the fetcher, the
|
|
43
42
|
writer in, rather than reaching for globals. This is what makes the pure
|
|
44
43
|
core testable.
|
|
@@ -10,10 +10,9 @@ shaped*.
|
|
|
10
10
|
|
|
11
11
|
- One module, one reason to change. A file that mixes HTTP parsing,
|
|
12
12
|
business rules, and persistence is three modules wearing one name.
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
boundary make business decisions or an entity reach for the network.
|
|
13
|
+
- Keep I/O and translation at the edge, business rules in the middle,
|
|
14
|
+
and state with its invariants in its own module. Don't let edge code
|
|
15
|
+
make business decisions or a data module reach for the network.
|
|
17
16
|
- A function does one thing at one level of abstraction. If you need "and"
|
|
18
17
|
to describe it, split it.
|
|
19
18
|
|
|
@@ -15,12 +15,12 @@ replace it.
|
|
|
15
15
|
|
|
16
16
|
| Loop phase | Invoke | What it feeds (the archik artifact) |
|
|
17
17
|
| --- | --- | --- |
|
|
18
|
-
| DESIGN — requirements | `superpowers:brainstorming` | Explore intent before committing. Output is the **archik
|
|
18
|
+
| DESIGN — requirements | `superpowers:brainstorming` | Explore intent before committing. Output is the **staged archik sidecar** (nodes, nesting, edges), *not* a separate spec doc. |
|
|
19
19
|
| BUILD — plan | `superpowers:writing-plans` | Turn the accepted models into the **numbered build plan** that goes through the plan gate. |
|
|
20
|
-
| BUILD — code | `superpowers:test-driven-development` | RED → GREEN → REFACTOR per
|
|
20
|
+
| BUILD — code | `superpowers:test-driven-development` | RED → GREEN → REFACTOR per plan step. Landing the code flips its node `proposed → active`. |
|
|
21
21
|
| BUILD — when stuck | `superpowers:systematic-debugging` | Root-cause a failure before patching. A fix that invalidates a model triggers the loop's back-edge to DESIGN. |
|
|
22
|
-
| VERIFY — before "done" | `superpowers:verification-before-completion` | Evidence before claiming a
|
|
23
|
-
| Pre-merge | `superpowers:requesting-code-review` | Review before integrating, alongside `archik
|
|
22
|
+
| VERIFY — before "done" | `superpowers:verification-before-completion` | Evidence before claiming a step is done. Gates the `proposed → active` flip and any "tests pass" claim. |
|
|
23
|
+
| Pre-merge | `superpowers:requesting-code-review` | Review before integrating, alongside `archik validate` / `archik drift` / `archik smells`. |
|
|
24
24
|
| Branch isolation | `superpowers:using-git-worktrees` | Isolate the workspace before executing a multi-step plan. |
|
|
25
25
|
|
|
26
26
|
## Precedence
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "archik",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams with a live browser canvas, headless SVG render in CI, and an installable Claude skill so the model treats the diagram as the spec.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"architecture",
|
|
@@ -27,12 +27,6 @@
|
|
|
27
27
|
"bin": {
|
|
28
28
|
"archik": "bin/archik.js"
|
|
29
29
|
},
|
|
30
|
-
"exports": {
|
|
31
|
-
"./trace": {
|
|
32
|
-
"types": "./dist/trace.d.ts",
|
|
33
|
-
"import": "./dist/trace.js"
|
|
34
|
-
}
|
|
35
|
-
},
|
|
36
30
|
"files": [
|
|
37
31
|
"bin",
|
|
38
32
|
"dist",
|