archik 0.12.47 → 0.12.49

package/docs/templates/principles/functional.md

@@ -0,0 +1,73 @@
+<!-- archik:principles:functional -->
+# Coding principles — Functional
+
+The rules below govern *how code is written* once the archik loop reaches
+BUILD. They sit underneath the engineering loop, not beside it: the loop
+decides *what* to build and *in what order*; these decide *how the code is
+shaped*.
+
+## Purity
+
+- Default to pure functions: output depends only on input, no observable
+  side effect. Same arguments, same result, every time.
+- A pure core is the testable core — it needs no mocks, no setup, no clock.
+  Most BUILD logic should land here.
+- When a function must do I/O, that's a signal it belongs at the edge, not
+  in the core (see "side effects at the edges").
+
+## Immutability
+
+- Treat data as immutable. Produce new values instead of mutating existing
+  ones; never reassign shared state in place.
+- No shared mutable state across modules. Shared mutability is where
+  concurrency bugs and spooky-action-at-a-distance live.
+- Model state transitions as functions `oldState -> newState`, returned and
+  threaded explicitly, not hidden in object fields.
+
+## Composition
+
+- Build behavior by composing small, total functions. The unit of reuse is
+  the function, not the class.
+- Prefer pipelines (`map` / `filter` / `reduce`, function composition) over
+  imperative loops with accumulators when the intent is a transformation.
+- Keep functions small and single-purpose so they compose cleanly. If a
+  function resists composition, it's probably doing two things.
+
+## Side effects at the edges
+
+- Push effects (I/O, network, DB, randomness, time) to the boundary of the
+  system; keep the interior pure. This maps directly onto the archik ECB
+  model: **boundary** code performs effects, **control** code is pure
+  orchestration, **entity** code is pure data + transitions.
+- Make effects explicit and injected — pass the clock, the fetcher, the
+  writer in, rather than reaching for globals. This is what makes the pure
+  core testable.
+- Isolate effectful code in thin, obvious shells so the dangerous parts are
+  small and easy to review.
+
+## Totality and explicit errors
+
+- Prefer total functions: defined for every input in their type. Narrow the
+  input type until the function can't fail, rather than guarding at runtime.
+- Make failure a value, not a thrown surprise — return a Result/Option/union
+  the caller must handle. No silent `null` leaks, no swallowed exceptions.
+- Handle every case explicitly; let exhaustiveness checking catch the ones
+  you forgot.
+
+## Declarative over imperative
+
+- Say *what*, not *how*. Express transformations and rules declaratively;
+  let the runtime handle the stepwise mechanics where possible.
+- Avoid hidden control flow. Data flow should be visible in the shape of the
+  code.
+- Comments explain *why*, never restate *what* (this mirrors the loop's
+  hard rules).
+
+## How this interacts with the loop
+
+- These principles shape the BUILD phase. They never override a HITL gate or
+  the requirements/structure/behavior/code ordering.
+- If applying a principle would change the component graph (e.g. splitting a
+  pure core out from an effectful shell as separate nodes), that's a
+  structural change — go back through the archik sidecar, don't just
+  refactor silently.

package/docs/templates/principles/oop.md

@@ -0,0 +1,72 @@
+<!-- archik:principles:oop -->
+# Coding principles — Object-Oriented
+
+The rules below govern *how code is written* once the archik loop reaches
+BUILD. They sit underneath the engineering loop, not beside it: the loop
+decides *what* to build and *in what order*; these decide *how the code is
+shaped*.
+
+## Separation of concerns
+
+- One module, one reason to change. A file that mixes HTTP parsing,
+  business rules, and persistence is three modules wearing one name.
+- Map concerns onto the ECB stereotypes already in the archik model:
+  **boundary** code handles I/O and translation, **control** code holds
+  use-case logic, **entity** code owns state and invariants. Don't let a
+  boundary make business decisions or an entity reach for the network.
+- A function does one thing at one level of abstraction. If you need "and"
+  to describe it, split it.
+
+## Composition over inheritance
+
+- Default to composition. Inheritance is for genuine *is-a* substitutability,
+  not code reuse — reuse via collaborators, not base classes.
+- Prefer small objects that delegate to injected collaborators over deep
+  class hierarchies. Depth past two levels is a smell.
+- Program to an interface (or the narrowest type that works), not a
+  concrete class, at module boundaries.
+
+## SOLID
+
+- **S**ingle responsibility — see separation of concerns above.
+- **O**pen/closed — extend behavior by adding a collaborator or
+  implementation, not by editing a switch that grows with every case.
+- **L**iskov — a subtype must be usable anywhere its supertype is, with no
+  surprises. If an override throws "not supported," the hierarchy is wrong.
+- **I**nterface segregation — many small role interfaces beat one fat one.
+  Callers depend only on the methods they use.
+- **D**ependency inversion — high-level policy depends on abstractions;
+  details (DB, HTTP, clock) are injected. This is what makes control logic
+  testable without the world attached.
+
+## Design patterns — used judiciously
+
+- Patterns are a vocabulary, not a goal. Reach for one when the forces it
+  resolves are actually present (e.g. Strategy when behavior varies by case,
+  Adapter at an external boundary, Repository to hide persistence).
+- Never introduce a pattern speculatively. A factory with one product or a
+  strategy with one strategy is accidental complexity — delete it.
+- Name the pattern in a comment only when the WHY isn't obvious from the
+  code.
+
+## Clean code
+
+- Names carry intent: `unsettledInvoices`, not `data2`. A good name removes
+  the need for a comment.
+- Small functions, few parameters. Past three or four parameters, introduce
+  a value object.
+- No dead code, no commented-out blocks, no speculative generality (YAGNI).
+- Encapsulate state: expose behavior, not raw fields. Invariants live with
+  the data they constrain so they can't be violated from outside.
+- Fail fast and explicitly. Validate at the boundary; let control and
+  entity code assume valid input.
+- Comments explain *why*, never restate *what* (this mirrors the loop's
+  hard rules).
+
+## How this interacts with the loop
+
+- These principles shape the BUILD phase. They never override a HITL gate or
+  the requirements/structure/behavior/code ordering.
+- If applying a principle would change the component graph (e.g. extracting
+  a new control object), that's a structural change — go back through the
+  archik sidecar, don't just refactor silently.

package/docs/templates/superpowers.md

@@ -0,0 +1,37 @@
+<!-- archik:superpowers -->
+# Superpowers ⨯ the engineering loop
+
+This project opted into the **superpowers** plugin. The skills below are
+wired into specific phases of the archik loop. At each phase, **invoke the
+named skill** — but the skill *feeds* the archik artifact, it does not
+replace it.
+
+> If a superpowers skill isn't available in this session, the loop still
+> stands on its own: `@.archik/ENGINEERING_LOOP.md` already describes the
+> same discipline inline. These references make it explicit and stronger
+> when the plugin is installed.
+
+## Phase → skill map
+
+| Loop phase | Invoke | What it feeds (the archik artifact) |
+| --- | --- | --- |
+| DESIGN — requirements | `superpowers:brainstorming` | Explore intent before committing. Output is the **archik requirements model** (actors + use cases + slices), *not* a separate spec doc. |
+| BUILD — plan | `superpowers:writing-plans` | Turn the accepted models into the **numbered build plan** that goes through the plan gate. |
+| BUILD — code | `superpowers:test-driven-development` | RED → GREEN → REFACTOR per slice. The tests it writes are the ones a slice names; landing them flips the slice `proposed → active`. |
+| 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. |
+| VERIFY — before "done" | `superpowers:verification-before-completion` | Evidence before claiming a slice is done. Gates the `proposed → active` flip and any "tests pass" claim. |
+| Pre-merge | `superpowers:requesting-code-review` | Review before integrating, alongside `archik trace` / `archik validate`. |
+| Branch isolation | `superpowers:using-git-worktrees` | Isolate the workspace before executing a multi-step plan. |
+
+## Precedence
+
+1. **User instructions** (this file, CLAUDE.md, direct requests) win.
+2. **The archik loop gates** (`@.archik/ENGINEERING_LOOP.md`) win over a
+   skill's own flow. Example: `brainstorming` wants to write its own spec
+   file and end by invoking `writing-plans` — here, the design artifact is
+   the archik requirements model, and the plan still goes through the archik
+   plan gate.
+3. **Superpowers skill discipline** applies within each phase.
+
+The rule of thumb: **use the skill to do the phase well; let archik decide
+what the phase produces and when the gate opens.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archik",
-  "version": "0.12.47",
+  "version": "0.12.49",
   "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.",
   "keywords": [
     "architecture",
@@ -34,6 +34,9 @@
     "docs/logo.svg",
     "docs/wordmark.svg",
     "docs/templates/CLAUDE.md",
+    "docs/templates/superpowers.md",
+    "docs/templates/principles/oop.md",
+    "docs/templates/principles/functional.md",
     "skills",
     "commands",
     ".claude-plugin",