archik 0.19.5 → 0.21.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 +32 -30
- package/commands/accept.md +21 -47
- package/commands/bootstrap.md +29 -28
- package/commands/evolve.md +19 -50
- package/commands/migrate.md +60 -60
- package/commands/self-evolving.md +8 -7
- package/commands/spawn.md +36 -38
- package/commands/suggest.md +47 -53
- package/dist/cli/archik.mjs +529 -572
- package/dist/ui/assets/index-B9OpuGHk.js +226 -0
- package/dist/ui/assets/index-DUgLHSFs.css +1 -0
- package/dist/ui/index.html +2 -2
- package/docs/templates/CLAUDE.md +73 -150
- 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 +71 -311
- 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-B9OpuGHk.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,65 +2,65 @@
|
|
|
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*. **Decision records** in `.archik/decisions/` say *why* it is shaped that way — one per accepted change. `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
|
|
|
18
|
+
### Match gates to reversibility
|
|
19
|
+
|
|
20
|
+
`archik suggest set` labels every change a **one-way door** (hard to undo) or a **two-way door** (easy to undo):
|
|
21
|
+
|
|
22
|
+
- **One-way door** — adds a data store, queue/stream, external system, gateway/auth/cdn, cloud or LLM node, a new edge to an external system, a top-level module; or removes a built node or moves one to another parent. Two separate stops: canvas gate first, then the plan gate. If it adds data, an outside system or public traffic, the decision record must also say how it is **secured, observed and rolled back** (`crossCutting`) — `suggest set` refuses it otherwise.
|
|
23
|
+
- **Two-way door** — everything else (an internal function, a new edge inside a module, a description, a lifecycle flip). One stop: stage the sidecar and show the build plan in the same message; `/archik:accept` approves both.
|
|
24
|
+
|
|
19
25
|
### Match ritual to scope
|
|
20
26
|
|
|
21
27
|
Not every task needs the full loop. Skip the modeling phases and just edit when the change is:
|
|
22
28
|
|
|
23
29
|
- 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
|
|
30
|
+
- A pure refactor that doesn't change the component graph or any user-visible behavior
|
|
25
31
|
- A bug fix inside an existing node that doesn't change its responsibility
|
|
26
32
|
|
|
27
|
-
Run the loop when the change introduces new behavior, a new structural shape, a new external interaction
|
|
33
|
+
Run the loop when the change introduces new behavior, a new structural shape, or a new external interaction.
|
|
28
34
|
|
|
29
35
|
### The five-phase loop
|
|
30
36
|
|
|
31
|
-
**DISCOVER → DESIGN → DECIDE → BUILD → VERIFY**, with one critical back-edge: if BUILD reveals
|
|
37
|
+
**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
38
|
|
|
33
|
-
- **DISCOVER** — `npx archik q stats / list
|
|
34
|
-
- **DESIGN** —
|
|
35
|
-
- **DECIDE** — `/archik:accept` on the structural sidecar
|
|
39
|
+
- **DISCOVER** — `npx archik q stats / list`, `npx archik smells`, `ls` source dirs. Read before write.
|
|
40
|
+
- **DESIGN** — structural sidecar plus its decision record (context, decision, alternatives, consequences).
|
|
41
|
+
- **DECIDE** — `/archik:accept` on the structural sidecar. Accept writes the decision record.
|
|
36
42
|
- **BUILD** — numbered plan → "approve" → execute in small commits. Tests-first when the behavior is clearly bounded.
|
|
37
|
-
- **VERIFY** — validate, tests, lint, build, `archik
|
|
43
|
+
- **VERIFY** — validate, tests, lint, build, `archik drift`, `archik smells`, eyeball UI. Stage the `proposed → active` flip.
|
|
38
44
|
|
|
39
45
|
The **per-milestone rhythm** below is the actionable checklist that walks these phases step-by-step.
|
|
40
46
|
|
|
41
|
-
### Worked example — one
|
|
47
|
+
### Worked example — one feature end-to-end
|
|
42
48
|
|
|
43
49
|
User says: *"add password reset by email."*
|
|
44
50
|
|
|
45
51
|
I'd run the loop like this:
|
|
46
52
|
|
|
47
|
-
1. **DISCOVER** — `npx archik q
|
|
48
|
-
|
|
49
|
-
2. **DESIGN (a) actors** — no new actor; skip.
|
|
53
|
+
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.
|
|
50
54
|
|
|
51
|
-
|
|
55
|
+
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. The draft's decision record: *context* — users who lose their password open support tickets; *decision* — self-service reset by emailed one-time link; *alternatives* — admin-only reset, SMS codes; *consequences* — we now depend on an email provider and must expire tokens. It adds an external system, so `suggest set` calls it a **one-way door** and the record also needs *crossCutting*: tokens are single-use and expire in 15 minutes, the provider key lives in the secret store (security); reset requests and send failures are counted and alerted (observability); a feature flag turns the reset link off (rollback). Wait for **`/archik:accept`** on the canvas; accept writes `.archik/decisions/0004-password-reset-by-email.md`.
|
|
52
56
|
|
|
53
|
-
|
|
57
|
+
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".
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
4. **Execute** — small commits. One per file roughly.
|
|
56
60
|
|
|
57
|
-
|
|
61
|
+
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.
|
|
58
62
|
|
|
59
|
-
|
|
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.
|
|
63
|
+
The flow produces two reviewable artifacts (diagram, plan) before code lands. Each is small. Neither is optional once the loop applies.
|
|
64
64
|
|
|
65
65
|
## First message — project brief
|
|
66
66
|
|
|
@@ -71,137 +71,74 @@ The recommended opener is **`/archik:bootstrap`** (with or without an inline bri
|
|
|
71
71
|
npx archik@latest init # fresh project — creates .archik/main.archik.yaml + slash commands
|
|
72
72
|
npx archik upgrade # already installed — pulls latest, refreshes SKILL.md + slash commands
|
|
73
73
|
```
|
|
74
|
-
Either path leaves the slash commands (`/archik:suggest`, `/archik:accept`, `/archik:
|
|
74
|
+
Either path leaves the slash commands (`/archik:suggest`, `/archik:accept`, `/archik:evolve`, etc.) and the live canvas (`npx archik dev`) in place.
|
|
75
75
|
|
|
76
|
-
2. **Read the current state** with `ls -F`, `npx archik q list
|
|
76
|
+
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
77
|
|
|
78
78
|
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
79
|
|
|
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.
|
|
80
|
+
4. **Stage the structural model** via `npx archik suggest set` — the **first milestone in detail** (every node and edge it needs, `status: proposed`), and the rest of the system as a few coarse `module` placeholders (one per later area, `status: proposed`, one-line description). Wait for **`/archik:accept`** on the canvas (formal gate).
|
|
83
81
|
|
|
84
|
-
|
|
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.
|
|
87
|
-
|
|
88
|
-
8. **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.
|
|
82
|
+
5. **Detail grows with the work.** Don't model what you can't yet know. Each milestone first details its own area (a sidecar that replaces the placeholder's insides), then flips those nodes from `proposed` to `active` (with `sourcePath`) as code lands. The set of nodes a milestone flips IS the milestone.
|
|
89
83
|
|
|
90
84
|
## Per-milestone rhythm
|
|
91
85
|
|
|
92
|
-
Every milestone follows the same shape.
|
|
93
|
-
|
|
94
|
-
1. **Author actors** — `/archik:actor <id>` if this milestone introduces new actors. Updates `.archik/actors.archik.actors.yaml`, validates, shows inline; wait for user confirmation.
|
|
95
|
-
2. **Author use case** — `/archik:usecase <name>`. Writes a `*.archik.uc.yaml` with basic + alternate flows, slices, and test paths. Slices whose tests don't exist on disk yet start `status: proposed`. Validates, shows inline; wait for user confirmation.
|
|
96
|
-
3. **Structural sidecar** — `/archik:suggest <feature>`. Stages the proposed end-state for this milestone via `npx archik suggest set` under the hood. Tag participating nodes with `stereotype: boundary | control | entity`. Rationale in 2–4 bullets. Every node listed as a seq participant must declare the seq in its own `seqFiles` array (the validator catches missing backrefs).
|
|
97
|
-
4. **`/archik:accept` on the structural diagram** — formal canvas gate. This is the only artifact with a canvas diff review.
|
|
98
|
-
5. **Author seq files** (direct-write) — for each non-trivial slice, write a `.archik.seq.yaml` with a `realizes: { useCase, slice }` block. Run `npx archik validate` after every write. Show inline; wait for user confirmation.
|
|
99
|
-
6. **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. For every seq diagram that realizes a slice: each message in the seq must map to a concrete function call in the plan — this is the traceability requirement.
|
|
100
|
-
7. **"approve" on the plan** — plan gate. Don't start editing files until approved.
|
|
101
|
-
8. **Execute** — small commits, narrate non-obvious decisions, declare back-edges to DESIGN openly when they happen.
|
|
102
|
-
9. **Verify** — project tests → lint → build → `/archik:trace` (or `npx archik trace`) → aesthetic eyeball (if UI). Trace must show no untraced active slices before the milestone closes; partials are tolerable mid-flight.
|
|
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
|
|
86
|
+
Every milestone follows the same shape. Two gate types apply — **canvas gate** (`/archik:accept`) and **plan gate** ("approve") — merged into one stop for two-way doors:
|
|
108
87
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
88
|
+
1. **Structural sidecar** — `/archik:suggest <feature>`. Stages the proposed end-state for this milestone via `npx archik suggest set` under the hood, with its decision record. Note whether `suggest set` called it a one-way or two-way door.
|
|
89
|
+
2. **`/archik:accept` on the structural diagram** — formal canvas gate.
|
|
90
|
+
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. For a one-way door with `crossCutting`, the plan also lands what it promised: the security control, the signal you will watch, the rollback path.
|
|
91
|
+
4. **"approve" on the plan** — plan gate. Don't start editing files until approved. *Two-way door:* steps 1–4 collapse — show the plan together with the sidecar, and `/archik:accept` approves both.
|
|
92
|
+
5. **Execute** — small commits, narrate non-obvious decisions, declare back-edges to DESIGN openly when they happen.
|
|
93
|
+
6. **Verify** — project tests → lint → build → `npx archik drift` → `npx archik smells` → aesthetic eyeball (if UI). No **new** folder loop or oversized file should close the milestone (with a committed baseline, `smells` marks them NEW). For a one-way door, check the `crossCutting` promises exist in the code before the flip to `active`.
|
|
94
|
+
7. **Stage the `proposed → active` sidecar** — `/archik:suggest "flip <list> to active"`. Flips nodes/edges with their `sourcePath` now on disk. Its decision record is short: what landed, and that drift now checks it.
|
|
95
|
+
8. **Hand off** — list what to eyeball; wait for `/archik:accept` and (if there's a deploy) confirm deploy is green.
|
|
96
|
+
9. **Commit + push** — only after the user confirms.
|
|
118
97
|
|
|
119
98
|
## Hard rules
|
|
120
99
|
|
|
121
|
-
1. **
|
|
122
|
-
2. **
|
|
123
|
-
3. **
|
|
124
|
-
4. **
|
|
125
|
-
5. **
|
|
126
|
-
6. **
|
|
127
|
-
7. **
|
|
128
|
-
8. **
|
|
129
|
-
9. **
|
|
130
|
-
10. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
|
|
100
|
+
1. **Structure → plan → code. In that order.** The accepted diagram defines what to build. Code lands last.
|
|
101
|
+
2. **Gates match reversibility.** One-way doors get two stops: a **canvas gate** (`/archik:accept`) on the model, then an **approval gate** ("approve") on the plan. Two-way doors get one stop: sidecar and plan shown together, one `/archik:accept`. Never skip review of a one-way door to save time.
|
|
102
|
+
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.
|
|
103
|
+
4. **Stop at every milestone boundary.** Summarize what shipped, run verifications (`archik drift` and `archik smells`), ask for the visual ack before continuing.
|
|
104
|
+
5. **Boring underneath.** No experimental framework features unless explicitly requested. Match the stack the brief specifies.
|
|
105
|
+
6. **No scope creep.** Out-of-scope items go in `FUTURE.md`, not the current milestone.
|
|
106
|
+
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.
|
|
107
|
+
8. **Every structural change says why.** Each sidecar carries a decision record; accept writes it to `.archik/decisions/`. Records are never edited — to change course, a new record lists the old numbers in `supersedes`.
|
|
108
|
+
9. **Don't add comments that restate code.** Add a comment only when the WHY is non-obvious.
|
|
131
109
|
|
|
132
110
|
## What each phase produces
|
|
133
111
|
|
|
134
112
|
### DISCOVER
|
|
135
113
|
- `npx archik q stats` and `npx archik q list` to ground in the current diagram.
|
|
136
|
-
- `npx archik
|
|
137
|
-
-
|
|
114
|
+
- `npx archik smells` to see folder loops and oversized files in the code.
|
|
115
|
+
- Past decision records in `.archik/decisions/` for the area you will touch — don't undo a choice without knowing why it was made.
|
|
138
116
|
- `ls -F` of relevant source dirs.
|
|
139
117
|
- A mental map of what exists vs what the request needs.
|
|
140
118
|
- No code, no diagram changes yet.
|
|
141
119
|
|
|
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
|
|
120
|
+
### DESIGN
|
|
157
121
|
- One-line intent.
|
|
158
122
|
- 1–3 clarifying questions only when there's genuine ambiguity.
|
|
159
123
|
- A sidecar staged via `npx archik suggest set --note "..."` containing the **full proposed end-state**.
|
|
124
|
+
- A decision record in the draft (`metadata.suggestion.decision`): **context** (the problem and forces, not the solution), **decision**, **alternatives** (at least one real option not chosen), **consequences** (what gets easier *and* harder). `suggest set` refuses a draft without it.
|
|
125
|
+
- For changes that add data, an outside system or public traffic: `crossCutting` with **security** (who can reach it, secrets, data exposure), **observability** (how you will see it work or fail) and **rollback** (how to undo it safely).
|
|
126
|
+
- Model only what this milestone needs in detail; later areas stay coarse placeholders.
|
|
160
127
|
- New code-bearing nodes use `status: proposed` and may omit `sourcePath`.
|
|
161
|
-
-
|
|
128
|
+
- Containers via `parentId`; a big subsystem gets its own sub-file via `archikFile`.
|
|
162
129
|
- `description` on every node explains *what it does*, not *what kind it is*.
|
|
163
130
|
- Bounded contexts named explicitly; cross-context calls default to async unless there's a reason.
|
|
164
131
|
- Public traffic routes through a `gateway`/`auth` node, not directly to a service.
|
|
165
132
|
|
|
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
133
|
### DECIDE
|
|
195
134
|
- The user runs `/archik:accept` (apply) or `/archik:reject` (with a reason).
|
|
135
|
+
- On accept: the decision record lands in `.archik/decisions/NNNN-<slug>.md`, with the model change listed as evidence.
|
|
196
136
|
- 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
137
|
|
|
199
138
|
### BUILD
|
|
200
139
|
- A numbered file-level plan, presented before any edit:
|
|
201
140
|
- Each new code-bearing node → its `sourcePath` and the concrete files / signatures.
|
|
202
141
|
- 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
142
|
- Default to **tests-first** when the behavior is clearly bounded.
|
|
206
143
|
- Out-of-scope items called out explicitly.
|
|
207
144
|
- Wait for "approve" before editing.
|
|
@@ -211,61 +148,47 @@ ECB rule violations when the seq diagram is validated.
|
|
|
211
148
|
1. Project tests — all passing.
|
|
212
149
|
2. Lint — clean.
|
|
213
150
|
3. Build / typecheck — clean.
|
|
214
|
-
4. `npx archik validate` — schema + cross-file +
|
|
215
|
-
5. `npx archik
|
|
216
|
-
6. `npx archik
|
|
217
|
-
7.
|
|
218
|
-
8.
|
|
219
|
-
9.
|
|
151
|
+
4. `npx archik validate` — schema + cross-file + constraint checks clean.
|
|
152
|
+
5. `npx archik drift` — structural model matches disk.
|
|
153
|
+
6. `npx archik smells` — no **new** folder loops or oversized files. On existing code, run `npx archik smells --update-baseline` once and commit `.archik/smells-baseline.json`; `--fail-on-warn` then fails CI only on new findings. Tighten the baseline when findings are fixed.
|
|
154
|
+
7. For one-way doors: the record's `crossCutting` promises (security control, signal, rollback path) exist in the code.
|
|
155
|
+
8. Aesthetic eyeball when there's a UI — share a screenshot, ask before declaring done.
|
|
156
|
+
9. Stage the `proposed → active` sidecar — flip nodes/edges with `sourcePath`.
|
|
220
157
|
10. Commit (with a Co-Authored-By line) and push — only after user confirms.
|
|
221
158
|
|
|
222
159
|
## Archik commands I use
|
|
223
160
|
|
|
224
161
|
**Reading the models:**
|
|
225
162
|
- `npx archik q list | edges | describe <id> | dependents <id> | impact <id>` — structural model.
|
|
226
|
-
- `npx archik q sequences [--node <id>]` — seq flows.
|
|
227
163
|
- `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.
|
|
164
|
+
- `npx archik affected [--since <ref>]` — changed files → nodes and their dependents.
|
|
231
165
|
|
|
232
166
|
**Authoring:**
|
|
233
167
|
- `npx archik schema` — once before authoring any sidecar.
|
|
234
|
-
- `npx archik schema uc` — use case schema.
|
|
235
|
-
- `npx archik schema actors` — actors schema.
|
|
236
168
|
- `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
169
|
|
|
239
170
|
**Lifecycle:**
|
|
240
|
-
- `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.
|
|
171
|
+
- `npx archik suggest accept | reject | show` — structural sidecar lifecycle. Accept writes the decision record.
|
|
172
|
+
- `npx archik validate` — schema + cross-file + constraint checks.
|
|
245
173
|
|
|
246
174
|
**Verification & rendering:**
|
|
247
175
|
- `npx archik drift` — source paths that no longer exist on disk.
|
|
176
|
+
- `npx archik smells [--fail-on-warn]` — folder import loops + oversized files, with import evidence.
|
|
248
177
|
- `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
178
|
|
|
251
179
|
## Common pitfalls
|
|
252
180
|
|
|
253
181
|
- **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
182
|
- **Writing prose-only summaries instead of staging a sidecar** — every structural change must produce a reviewable artifact.
|
|
261
|
-
- **Skipping the BUILD-plan HITL** —
|
|
262
|
-
- **
|
|
263
|
-
- **
|
|
264
|
-
- **
|
|
183
|
+
- **Skipping the BUILD-plan HITL** — diagram acceptance is not implicit code approval.
|
|
184
|
+
- **A decision record with only upsides** — consequences must name what gets harder too; alternatives must be options you really weighed.
|
|
185
|
+
- **Editing an old decision record** — records are history. Stage a new decision that `supersedes` it.
|
|
186
|
+
- **Renaming an `id` mid-flow** — forbidden; remove the old and add a new one. Renames break diff and require manual re-link in code.
|
|
187
|
+
- **Labelling a smell without evidence** — name a folder loop by the imports `archik smells` shows, not by a made-up category.
|
|
265
188
|
|
|
266
189
|
## Working with this file
|
|
267
190
|
|
|
268
191
|
- This is `CLAUDE.md`. Future Claude sessions read it first.
|
|
269
192
|
- I add an `@AGENTS.md` line at the top if the project has framework-specific agent rules.
|
|
270
193
|
- 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
|
-
-
|
|
194
|
+
- 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.21.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",
|