Merge remote-tracking branch 'origin/master' into feat/data-layer-monitor

# Conflicts:
#	.agent/skills/_index.md
#	.agent/skills/_manifest.jsonl

Author: codejunkie99

.agent/AGENTS.md

@@ -41,6 +41,19 @@ are the exact failure mode this layer prevents.
 - Load a full `SKILL.md` only when its triggers match the current task
 - Every skill has a self-rewrite hook; invoke it after failures
 
+## Design Systems
+- If the project root contains `DESIGN.md`, treat it as the source of truth
+  for visual design decisions and load `skills/design-md/SKILL.md` when a
+  task mentions `DESIGN.md`, Google Stitch, design tokens, design system,
+  or visual design. (The skill's `preconditions` field gates loading on
+  `DESIGN.md` actually existing — keep this rule in lockstep with
+  `skills/_manifest.jsonl` to avoid same-task / different-harness drift.)
+- Prefer exact tokens, component rules, and design rationale from
+  `DESIGN.md` over invented colors, typography, spacing, shadows, or motion.
+- Do not modify `DESIGN.md` unless the user explicitly asks for a design
+  system change; implementation work consumes the contract, it doesn't
+  edit it.
+
 ## Protocols
 - `protocols/permissions.md` — read before any tool call
 - `protocols/tool_schemas/` — typed interfaces for external tools

.agent/memory/semantic/DECISIONS.md

@@ -14,3 +14,9 @@
 **Rationale:** Each layer has different retention and retrieval needs. Flat memory breaks at ~6 weeks.
 **Alternatives considered:** Flat directory (fails at scale), vector store (over-engineered for single user).
 **Status:** active
+
+## 2026-04-26: Add `design-md` seed skill (DESIGN.md / Google Stitch)
+**Decision:** Ship a sixth seed skill, `design-md`, that points coding agents at a root `DESIGN.md` (Google Stitch format) as the visual-system source of truth. Loads only when `DESIGN.md` exists at the project root, default behavior is read-only on the contract file, and validation prefers `npx @google/design.md lint DESIGN.md` over hand-checks.
+**Rationale:** `DESIGN.md` is becoming a de facto contract for AI-driven UI work; without an explicit skill, agents invent ad-hoc tokens that drift from the user's design system. Gating on `DESIGN.md`-existence keeps the skill silent on projects that don't use the format.
+**Alternatives considered:** Bundle the rules into `git-proxy` or `skillforge` (wrong scope, wrong triggers); leave it to per-project `.agent/skills/` overrides (loses the cross-harness benefit); broader triggers like "UI"/"frontend"/"components"/"styling" (too generic, loads on every UI task even without DESIGN.md).
+**Status:** active

.agent/skills/_index.md

@@ -33,3 +33,15 @@ Triggers: "data layer", "dashboard", "agent analytics", "resource usage",
 "cron monitoring", "daily report", "tokens"
 Constraints: local-only by default; no screenshot delivery without explicit user
 approval; do not commit private `.agent/data-layer/` exports.
+
+## design-md
+Uses a root `DESIGN.md` as the portable visual system contract for
+Google Stitch workflows. Loads only when `DESIGN.md` exists at the
+project root.
+Triggers: "DESIGN.md", "design.md", "Google Stitch", "design tokens",
+"design system", "visual design"
+Preconditions: DESIGN.md exists at project root.
+Constraints: prefer DESIGN.md tokens over invented values, do not modify
+DESIGN.md unless the user explicitly asks, preserve unknown sections when
+an edit IS authorised, validate with `npx @google/design.md lint DESIGN.md`
+when available.

.agent/skills/_manifest.jsonl

@@ -4,3 +4,4 @@
 {"name":"debug-investigator","version":"2026-01-01","triggers":["debug","why is this failing","investigate","stack trace","bug"],"tools":["bash","memory_reflect"],"preconditions":[],"constraints":["reproduce before fixing","fix root cause, not symptoms"],"category":"engineering"}
 {"name":"deploy-checklist","version":"2026-01-01","triggers":["deploy","ship","release","go live"],"tools":["bash"],"preconditions":[],"constraints":["all tests passing","no unresolved TODOs in diff","requires human approval for production"],"category":"operations"}
 {"name":"data-layer","version":"2026-04-25","triggers":["data layer","dashboard","agent analytics","resource usage","cron monitoring","daily report","tokens"],"tools":["bash","git"],"preconditions":[".agent exists"],"constraints":["local-only by default","no screenshot delivery without explicit user approval","do not commit private .agent/data-layer exports"],"category":"operations"}
+{"name":"design-md","version":"2026-04-26","triggers":["DESIGN.md","design.md","Google Stitch","Stitch","design tokens","design system","visual design"],"tools":["bash","memory_reflect"],"preconditions":["DESIGN.md exists at project root"],"constraints":["prefer DESIGN.md tokens over invented values","do not modify DESIGN.md unless the user explicitly asks","preserve unknown sections when an edit IS authorised","validate when tooling is available"],"category":"design"}

.agent/skills/design-md/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: design-md
+version: 2026-04-26
+triggers: ["DESIGN.md", "design.md", "Google Stitch", "Stitch", "design tokens", "design system", "visual design"]
+tools: [bash, memory_reflect]
+preconditions: ["DESIGN.md exists at project root"]
+constraints: ["prefer DESIGN.md tokens over invented values", "do not modify DESIGN.md unless the user explicitly asks", "preserve unknown sections when an edit IS authorised", "validate when tooling is available"]
+---
+
+# DESIGN.md — portable visual system contract
+
+Use this skill when a task touches Google Stitch's `DESIGN.md` format or
+the project explicitly references its design system / design tokens. The
+skill loads only when `DESIGN.md` exists at the project root (see
+`preconditions` above), so general UI / frontend / component work that
+isn't tied to a `DESIGN.md` won't trip it.
+
+## Source of truth
+- `DESIGN.md` is a contract file. Read it before changing visual UI.
+- Treat YAML front matter tokens as normative values: colors, typography,
+  spacing, radius, and component tokens are exact inputs to code.
+- Treat the Markdown body as design rationale: it explains mood, hierarchy,
+  interaction intent, and where tokens should or should not be used.
+- If no `DESIGN.md` exists this skill is inactive; for new UI, offer to
+  create one or ask for a brand/reference, but don't generate one
+  unprompted.
+
+## Default: read-only
+**Do not modify `DESIGN.md` unless the user explicitly asks for a design
+system change.** Implementation work consumes the contract; it does not
+edit it. Token additions, renames, or section restructures land in their
+own commit with a clear message and (ideally) a Stitch round-trip.
+
+## Implementation rules
+1. Map tokens into the local styling system already in use: CSS variables,
+   Tailwind theme values, design-token JSON, component props, or native
+   styles.
+2. Use token references and component patterns from `DESIGN.md` instead of
+   hard-coded one-off values.
+3. Keep accessibility constraints intact. Do not weaken contrast, focus,
+   reduced-motion, or touch-target guidance unless the user explicitly
+   asks.
+
+## When an edit IS authorised
+1. Preserve unknown headings and extra prose; other agents or Stitch may
+   own them.
+2. Express component variants as related entries
+   (`button-primary`, `button-primary-hover`, etc.).
+3. Land token / structure changes in their own commit, separate from the
+   feature consuming them.
+
+## Validation
+- If Node/npm tooling is available, lint with:
+
+  ```bash
+  npx @google/design.md lint DESIGN.md
+  ```
+
+- For design system changes, diff before/after:
+
+  ```bash
+  npx @google/design.md diff DESIGN.before.md DESIGN.md
+  ```
+
+- If the CLI is unavailable or network/dependency policy blocks it, the
+  manual fallback is best-effort only — check for broken `{path.to.token}`
+  references, missing primary color / typography tokens, duplicate section
+  headings, and section order. The CLI ALSO checks contrast ratios and
+  orphaned tokens; the manual fallback does not, so re-run the CLI when
+  you regain network access.
+
+## Expected sections
+The Google draft spec uses YAML front matter plus Markdown sections.
+Common sections:
+
+- `## Overview`
+- `## Colors`
+- `## Typography`
+- `## Layout`
+- `## Elevation & Depth`
+- `## Shapes`
+- `## Components`
+- `## Do's and Don'ts`
+
+## Self-rewrite hook
+After every 5 uses OR on any failure:
+1. Read the last N skill-specific episodic entries.
+2. If a new failure mode has appeared (e.g. tokens drifting away from
+   DESIGN.md, accessibility rules being weakened, unauthorised edits to
+   the contract file), append it to this skill's `KNOWLEDGE.md`.
+3. If a constraint was violated, escalate to `semantic/LESSONS.md`.
+4. Commit: `skill-update: design-md, <one-line reason>`.

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] — 2026-04-26
+
+Minor release. Adds the `design-md` seed skill (sixth seed skill in the
+brain), and fixes a hard crash on macOS-default Python 3.9 that hit every
+brew user on first run.
+
+### Added
+- **`design-md` seed skill — DESIGN.md / Google Stitch support.** A new
+  portable skill that points coding agents at a root `DESIGN.md` (Google
+  Stitch format) as the visual-system source of truth. Loads only when
+  `DESIGN.md` exists at the project root; default behavior is read-only on
+  the contract file, and validation prefers
+  `npx @google/design.md lint DESIGN.md` over hand-checks. Brings the seed
+  skill count from five to six. Thanks to @danielfoch for the contribution
+  (PR #21). Decision recorded in `.agent/memory/semantic/DECISIONS.md`.
+
+### Fixed
+- **Python 3.9 crash on first run (#27).** Every brew user on macOS-default
+  Python 3.9 hit `TypeError: unsupported operand type(s) for |: 'type' and
+  'type'` immediately after `brew install agentic-stack` because
+  `harness_manager/` used PEP 604 union syntax (`Path | str`) that requires
+  Python 3.10+ at runtime. Added `from __future__ import annotations`
+  (PEP 563) to the eight affected files so all annotations are stored as
+  strings and never evaluated at import time. Works on Python 3.7+, which
+  covers every macOS-shipped Python in the wild. Zero-cost vs. the
+  reporter's suggested `python@3.10` brew dep (~150 MB pull). Thanks to
+  @WhoLsJohnGalt for the precise repro and the suggested workaround.
+
+### Migration
+`brew upgrade agentic-stack` is enough — no on-disk schema changes. Users
+on Python 3.9 who hit #27 on v0.9.x can upgrade and the crash goes away.
+Users with existing `.pi/extensions/memory-hook.ts` from v0.9.0 already
+got the fixes via `./install.sh pi` after the v0.9.1 upgrade; this release
+adds the `design-md` skill on top.
+
+### Release
+- Tag `v0.10.0` cut from master.
+- GitHub release: <https://github.com/codejunkie99/agentic-stack/releases/tag/v0.10.0>
+- `Formula/agentic-stack.rb` bumped to v0.10.0 in a follow-up commit
+  (same flow as v0.8.0 → v0.9.0 → v0.9.1): tag first, compute sha256,
+  then bump `url` + `sha256` + `version` together so brew always points
+  at a real installable artifact.
+
+### Credits
+- PR #21 by @danielfoch (design-md skill), with cross-model review fixes
+  applied as a follow-up commit.
+- Issue #27 by @WhoLsJohnGalt — clean repro of the macOS Python 3.9 crash
+  including a working sed-based workaround.
+
 ## [0.9.1] — 2026-04-26
 
 Patch release that closes the gap between v0.9.0 and a working pi adapter.

Formula/agentic-stack.rb

@@ -1,9 +1,9 @@
 class AgenticStack < Formula
   desc "One brain, many harnesses — portable .agent/ folder for AI coding agents"
   homepage "https://github.com/codejunkie99/agentic-stack"
-  url "https://github.com/codejunkie99/agentic-stack/archive/refs/tags/v0.9.1.tar.gz"
-  sha256 "09cc3b8c9ec159cf8b85cf672fc15a29e6bfa9377cc9c59dd270acd441ced568"
-  version "0.9.1"
+  url "https://github.com/codejunkie99/agentic-stack/archive/refs/tags/v0.10.0.tar.gz"
+  sha256 "5d1e7de9478bdeaf684b0b2eb600e597886aeab52dda8494c7e304cceb0f1438"
+  version "0.10.0"
   license "Apache-2.0"
 
   def install

README.md

@@ -17,27 +17,31 @@ screenshot-ready daily dashboards.
   <img src="docs/diagram.svg" alt="agentic-stack architecture" width="880"/>
 </p>
 
-### New in v0.9.1 — pi adapter fixes + tz correctness
-
-Patch release. Closes the gap between v0.9.0 and a working pi adapter,
-plus a timezone sweep across every Python writer/reader so the dream
-cycle stops drifting against the UTC decay window.
-
-- Brew users on v0.9.0 hit `ModuleNotFoundError: harness_manager` on
-  first run. Formula now installs `harness_manager/` correctly.
-- Pi's dream cycle never fired (`session_shutdown` filter rejected every
-  event because `SessionShutdownEvent` has no `reason` field). Now runs.
-- Pi's edit reflections were missing the diff (hook expected MultiEdit
-  shape; Pi's edit input is flat). Now captures `oldText` / `newText`.
-- Naive-local Python timestamps reinterpreted at decay time as UTC
-  caused silent drift. Every writer now emits aware UTC; every reader
-  normalises naive entries before comparing.
-- `auto_dream` held no lock across its read-modify-write window —
-  concurrent appenders could be silently truncated. Now holds a single
-  `flock(LOCK_EX)` on the episodic log for the full cycle.
+### New in v0.10.0 — design-md skill + Python 3.9 fix
+
+Minor release. Adds a sixth seed skill and unbreaks `brew install` for
+every macOS user on the system Python.
+
+- **`design-md` seed skill.** Drop a Google Stitch-style `DESIGN.md` in
+  your project root and the skill points coding agents at it as the
+  visual-system source of truth — colors, typography, spacing, components,
+  rationale. Loads only when `DESIGN.md` exists; default behavior is
+  read-only on the contract file.
+- **Python 3.9 crash on first run is fixed (#27).** Every brew user on
+  macOS-default Python 3.9 hit `TypeError: unsupported operand type(s) for
+  |: 'type' and 'type'` immediately after install. Root cause: PEP 604
+  union annotations (`Path | str`) that require Python 3.10+. Fixed by
+  adding `from __future__ import annotations` to the eight affected
+  `harness_manager/` files; works on Python 3.7+.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full list.
 
+### v0.9.1 — pi adapter fixes + tz correctness
+
+Closed the gap between v0.9.0 and a working pi adapter, plus a timezone
+sweep across every Python writer/reader so the dream cycle stops drifting
+against the UTC decay window.
+
 ### v0.9.0 — harness manager
 
 <p align="center">
@@ -193,7 +197,7 @@ See [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.
 
 Every guide shows the folder structure. This repo gives you the folder
 structure **plus the files that actually go inside**: a working portable
-brain with five seed skills, four memory layers, enforced permissions, a
+brain with six seed skills, four memory layers, enforced permissions, a
 nightly staging cycle, host-agent review tools, and adapters for multiple
 harnesses.
 
@@ -206,7 +210,9 @@ harnesses.
   a required rationale. No unattended reasoning, no provider coupling.
 - **Skills** — progressive disclosure. A lightweight manifest always
   loads; full `SKILL.md` files only load when triggers match the task.
-  Every skill ships with a self-rewrite hook.
+  Every skill ships with a self-rewrite hook. The bundled `design-md`
+  skill teaches agents to use a root `DESIGN.md` as the visual source of
+  truth for UI and Google Stitch workflows.
 - **Protocols** — typed tool schemas, a `permissions.md` that the
   pre-tool-call hook enforces, and a delegation contract for sub-agents.
 - **Data layer** — local-only dashboard exports across every harness sharing
@@ -328,6 +334,8 @@ verify_codex_fixes.py           # v0.8.0 regression checks (33 checks)
 - **git-proxy** — all git ops, with safety constraints
 - **debug-investigator** — reproduce → isolate → hypothesize → verify
 - **deploy-checklist** — the fence between staging and production
+- **design-md** — uses Google Stitch-style `DESIGN.md` files as portable
+  design-system context for UI, frontend, and component work
 
 ## How it compounds
 

docs/demo/src/scenes/Outro.tsx

@@ -3,7 +3,7 @@ import { COLORS, FONT } from "../tokens";
 
 const STATS = [
   { value: "7", label: "harnesses" },
-  { value: "5", label: "seed skills" },
+  { value: "6", label: "seed skills" },
   { value: "4", label: "memory layers" },
 ];
 

docs/getting-started.md

@@ -42,6 +42,19 @@ Open your harness and ask it anything. The first few days it will feel
 stateless. After ~2 weeks you'll notice it checking past lessons, logging
 failures with reflection, and (if you let it) proposing skill rewrites.
 
+## Optional: add a visual system with `DESIGN.md`
+
+If your project has UI, drop a Google Stitch-style `DESIGN.md` file in the
+project root. The bundled `design-md` skill tells compatible agents to use
+that file as the source of truth for colors, typography, spacing, component
+rules, and design rationale instead of inventing visual choices.
+
+When Node tooling is available, agents can validate the file with:
+
+```bash
+npx @google/design.md lint DESIGN.md
+```
+
 ## Verify the wiring
 ```bash
 python3 .agent/tools/budget_tracker.py "commit and push"