@sassywares/agents 0.0.0-stage → 0.1.1

package/CONCEPTS.md

@@ -0,0 +1,45 @@
+# Sassy Agents — Concepts
+
+## Source of truth
+
+Each harness directory is the only copy of that harness's roster. `scripts/install.sh <harness>` symlinks each file into the harness's user agent directory (`~/.pi/agent/agents/`, `~/.claude/agents/`), so the running agents are the working tree.
+
+## Agent
+
+A Markdown file with `name` and `description` frontmatter, plus optional `tools`, `model`, `thinking`, and `profiles`. The body is the system prompt. One file, one role. See the [pi agent format](https://github.com/earendil-works/pi).
+
+## Harness
+
+A directory at the repo root named after the tool that consumes it: `pi/` for pi, `claude/` for Claude Code. Every harness directory holds the full roster. Harnesses differ in frontmatter and discovery only: an agent's body — what it does — is identical in every harness, and CI fails when it drifts.
+
+## Roster
+
+The four agents shipped here — `scout`, `worker`, `reviewer`, `validator` — and the contract that they cover a unit of work end to end: ground it, implement it, review it, validate it against intent.
+
+## Profile
+
+A named model choice inside an agent's `profiles:` list, such as `deepseek` or `anthropic`. A dispatch selects a profile; the agent's entry supplies the model and thinking level for that provider. Profiles are how one roster runs on several providers without a branch or a second copy.
+
+## Profile selection
+
+The precedence that resolves which profile a dispatch runs: the tool call's `profile` parameter, then `PI_SASSY_PROFILE`, then `sassy.profile` in project settings, then user settings, then the default `deepseek`. A missing profile is an error naming the available ones — never a silent fallback.
+
+## Scope
+
+Where an agent is discovered from. `user` is `~/.pi/agent/agents/`, the target of `scripts/install.sh`. `project` is the nearest project `.pi/agents/`, which overrides a user agent of the same name. The `subagent` tool takes `user`, `project`, or `both`; the default is `both`.
+
+## Grounding brief
+
+One file per repo or worktree, in a per-user temp directory, written by `scout` and read by every other agent in the run. It carries project evidence with `file:line` citations so consumers do not repeat discovery. Location, freshness, and wait rules are in [GROUNDING.md](GROUNDING.md).
+
+## Subagent
+
+The tool from `@sassywares/pi-extensions` that spawns one pi process per task and returns compact output. Modes are single, parallel, and chain. This repo supplies the agents it dispatches; it does not implement the tool.
+
+## Orchestrator
+
+A skill from `sassy-skills` that coordinates: it decides which agents to dispatch, writes the brief, and keeps the main context small. Orchestrators live in the skills repo, not here.
+
+## Upstream derivation
+
+The roster is a modified version of pi's MIT-licensed examples and documentation. `NOTICE` records the attribution; `LICENSE` covers this repository.

package/GROUNDING.md

@@ -0,0 +1,60 @@
+# Grounding brief
+
+Every subagent in a run reads one shared grounding brief instead of exploring the repo for itself. `scout` writes it; `reviewer`, `validator`, and `worker` consume it.
+
+## Location
+
+A per-user temp directory, keyed by the absolute repo or worktree root:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+```
+
+For example, `tap2-workspace` resolves to `/tmp/pi-grounding-501/<sha>.md`. The directory is `0700` and owned by the current user; a symlinked or foreign-owned root aborts rather than being followed, because the brief is read as trusted-ish context by later agents.
+
+Keying on the worktree root means:
+
+- Two repos, or two worktrees of one repo, never share a brief.
+- A non-git folder still gets a stable location (hash of `$PWD`), so a scout and a consumer launched from the same directory agree.
+- Nothing is written into the repo, so there is no `.gitignore` entry and nothing to commit.
+- `/tmp` is cleared on reboot, which is the desired lifetime for a brief describing a working tree.
+
+## Freshness
+
+A brief is usable when all four hold:
+
+1. `repo` matches the current `ROOT_ABS`.
+2. `head` matches `git rev-parse HEAD`.
+3. `dirty` matches the current digest of `git status --porcelain`, `git diff`, and `git diff --cached` combined.
+4. `scope` covers what the consumer is about to ask.
+
+The digest covers statuses and diffs, not statuses alone: `git status --porcelain` reports ` M path` no matter what changed inside the file, so a status-only digest leaves a brief "fresh" after further edits to an already-dirty file. Including the diffs closes that. Any commit, edit, staged change, or new untracked file changes the digest and invalidates the brief; for a non-git folder the digest is empty, so freshness there rests on `scope` and `written` alone.
+
+## Waiting
+
+Consumers wait for a stale brief to be rewritten, never for one that does not exist. Waiting is token-free:
+
+```bash
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+```
+
+Sixty seconds is the ceiling. A missing brief reports `grounding: missing`; a brief that never refreshes reports `grounding: stale`. Either way the consumer does **at most 5 bounded reads** to fill the gap and says so in its output. It never runs a broad discovery pass and never becomes a second scout.
+
+## Sequencing
+
+The orchestrator dispatches `scout` first and awaits it, then dispatches the rest. Agents dispatched without the path still resolve the default location themselves, so a brief written by any earlier agent is reused.
+
+## What the brief is not
+
+It is not a cache across commits and not a substitute for judging evidence. A stale or thin brief is a finding the consumer reports, not something it silently papers over.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sassywares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+# Notice
+
+The agent definitions under `pi/` and `claude/` are derived from the examples and
+documentation of [pi](https://github.com/earendil-works/pi), Copyright (c) Mario
+Zechner and contributors, licensed under the MIT License.
+
+They have been modified for the Sassywares workflow: the Sassy roster, profile
+selection, and the shared grounding brief. See `LICENSE` for the license
+covering this repository.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# Sassy Agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The Sassy subagent roster — one directory per harness, one behavior in every harness, one roster on every provider.**
+
+Sassy Agents is the source of truth for the subagents the Sassywares workflow dispatches: a grounding scout, an implementation worker, a reviewer, and a validator. Each agent is a Markdown file with frontmatter; each declares a `profiles:` list, so the same roster runs on DeepSeek by default and on Anthropic when a project opts in.
+
+The repo is `sassy-agents`. The npm mirror is `@sassywares/agents`.
+
+## Table of contents
+
+- [Why this roster](#why-this-roster)
+- [Quick start](#quick-start)
+- [Agents](#agents)
+- [How agents are found](#how-agents-are-found)
+- [Model profiles](#model-profiles)
+- [Grounding brief](#grounding-brief)
+- [Harness layout](#harness-layout)
+- [Adding or editing an agent](#adding-or-editing-an-agent)
+- [Repository layout](#repository-layout)
+- [Development](#development)
+- [Repository maintenance](#repository-maintenance)
+- [Provenance](#provenance)
+
+## Why this roster
+
+- **One job per agent.** Scout grounds, worker implements, reviewer judges quality, validator judges intent. None of them re-does another's work.
+- **Isolated context.** Each is dispatched by the `subagent` tool from [`sassy-pi-extensions`](https://github.com/sassywares/sassy-pi-extensions), so each gets its own context window and returns a compact result.
+- **Provider-agnostic.** Model choice lives in frontmatter `profiles:`, not in a branch or a separate roster. Swapping providers is a settings change.
+- **Read-only by default.** Reviewer and validator get `read, grep, find, ls, bash`; only scout and worker can write.
+- **Shared grounding.** Every agent reads one brief written by `scout` instead of re-exploring the repo. See [GROUNDING.md](GROUNDING.md).
+- **Composable with [`sassy-skills`](https://github.com/sassywares/sassy-skills).** The skills dispatch these agents by name — `scout`, `worker`, `reviewer`, `validator`.
+
+## Quick start
+
+Clone the repo next to your work and link the roster for your harness:
+
+```bash
+git clone https://github.com/sassywares/sassy-agents.git
+./sassy-agents/scripts/install.sh          # pi → ~/.pi/agent/agents/
+./sassy-agents/scripts/install.sh claude   # Claude Code → ~/.claude/agents/
+```
+
+`sassy-setup` (in `sassy-skills`) checks for the roster and offers this link, or a per-project copy into `.pi/agents/` / `.claude/agents/`.
+
+`install.sh` symlinks `pi/*.md` into `~/.pi/agent/agents/`. Editing this repo changes the running agents on the next subagent invocation — there is no copy to keep in sync.
+
+Then install the extensions that dispatch them, if you have not already:
+
+```bash
+pi install npm:@sassywares/pi-extensions
+```
+
+Reload pi (`/reload`) and confirm the `subagent` tool lists the Sassy agents.
+
+A package-only install of `@sassywares/agents` works too when you would rather pin a version than link a checkout:
+
+```bash
+npm install --save-dev @sassywares/agents@0.1.0
+./node_modules/@sassywares/agents/scripts/install.sh
+```
+
+Pi does not load agents from packages on its own; the link step is what makes them visible.
+
+## Agents
+
+| Agent | Role | pi `deepseek` profile | pi `anthropic` profile | Claude Code `model` |
+|---|---|---|---|---|
+| `scout` | Grounding scout: writes the shared grounding brief other agents read, including matching prior learnings from the project's `.sassywares/config.yaml` knowledge paths. | `deepseek/deepseek-flash` | `anthropic/claude-haiku-4-5` | `haiku` |
+| `worker` | General-purpose implementation in an isolated context. | `deepseek/deepseek-flash` | `anthropic/claude-sonnet-4-5` | `sonnet` |
+| `reviewer` | Quality, correctness, security, project-rule, and design-system review, diff-scoped. | `deepseek/deepseek-flash` | `anthropic/claude-opus-4-5` | `opus` |
+| `validator` | Checks that the diff matches the plan, independent of review. | `deepseek/deepseek-flash` | `anthropic/claude-sonnet-4-5` | `sonnet` |
+
+Each file's body is the system prompt. Keep it to the role, hard rules, scope, and return shape — the orchestrating skill supplies the task. The body is identical in every harness directory; only the frontmatter is harness-specific, and CI fails on drift.
+
+## How agents are found
+
+Claude Code discovers agents from `~/.claude/agents/` (user) and the project's `.claude/agents/` (project, which wins on a name clash).
+
+In pi, the `subagent` extension discovers agents from:
+
+- `~/.pi/agent/agents/` — user scope, where `scripts/install.sh` links this roster.
+- The nearest project `.pi/agents/` — project scope, which overrides a user agent with the same name.
+
+`PI_AGENTS_DIR` overrides the user target when linking, which is useful in a container or a test harness. The extension's `agentScope` parameter (`user`, `project`, `both`) decides which of the two a dispatch sees; the default is `both`.
+
+## Model profiles
+
+A dispatch picks a profile — a named model choice — and the child process starts on that profile's model.
+
+Pick a profile three ways, highest precedence first:
+
+1. The tool call: `{ agent: "worker", task: "…", profile: "anthropic" }`. Individual `tasks[]` and `chain[]` entries accept `profile` too.
+2. An environment variable: `PI_SASSY_PROFILE=anthropic`.
+3. A project setting in `.pi/settings.json`, which is where a project opts in once for everyone:
+
+   ```json
+   { "sassy": { "profile": "anthropic" } }
+   ```
+
+   Project settings override `~/.pi/agent/settings.json`; with neither set, the default profile is `deepseek`.
+
+A profile an agent does not define is an error naming the ones it does — it never falls back to the default provider. The run footer shows the model and, in parentheses, the profile it came from.
+
+Every agent must define every profile a project may select. Adding a profile is a frontmatter edit in each file you want it to apply to:
+
+```yaml
+profiles:
+  - name: deepseek
+    model: deepseek/deepseek-flash
+    thinking: low
+  - name: anthropic
+    model: anthropic/claude-sonnet-4-5
+    thinking: low
+```
+
+Rules:
+
+- Profile names are lowercase letters, digits, and dashes, and must be unique within an agent.
+- `model` is always `provider/id`; `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.
+- `profiles:` and `model:` are mutually exclusive — pinning a model and offering profiles at once is a parse error.
+- A pinned `model:` (plus optional `thinking:`) is still supported for personal agents and ignores profile selection.
+- Neither key means the agent inherits the dispatcher's model and thinking.
+
+## Grounding brief
+
+Every agent in a run reads one shared brief instead of exploring the repo for itself. `scout` writes it; `worker`, `reviewer`, and `validator` consume it. It lives in a per-user temp directory keyed by the absolute repo or worktree root, so it never touches the repo and two worktrees never collide.
+
+[GROUNDING.md](GROUNDING.md) defines the location, the freshness check, and the wait rule. A missing or stale brief is reported, never papered over.
+
+## Harness layout
+
+One directory per harness: `pi/` and `claude/`. Every directory carries the full roster with identical bodies; only frontmatter differs.
+
+```text
+sassy-agents/
+├── pi/                  # pi subagent definitions
+│   ├── scout.md
+│   ├── worker.md
+│   ├── reviewer.md
+│   └── validator.md
+├── claude/              # Claude Code subagent definitions (same four)
+├── scripts/
+│   ├── install.sh       # links one harness's agents into place
+│   ├── sync.sh          # bump, commit, push, tag
+│   └── test-profiles.mjs
+└── …
+```
+
+`scripts/install.sh <harness>` takes `pi` (the default) or `claude` and rejects a harness it does not know, rather than guessing a target directory.
+
+## Adding or editing an agent
+
+1. Create or edit the agent in every harness directory: `pi/<name>.md` (`profiles:` or a pinned `model:`) and `claude/<name>.md` (Claude Code `tools` and a `model:` alias).
+2. Keep the frontmatter `name` equal to the file name.
+3. Keep the body focused on the role, hard rules, scope, and return shape — and byte-identical across harnesses.
+4. Update the roster table in `README.md`.
+5. Run `./scripts/install.sh` once if the agent is new, then `./scripts/sync.sh` to commit and release.
+
+Agents that write should say so in `tools:`: `scout` needs `write` (`Write` in Claude Code) for the brief, `worker` needs the full toolset. Reviewer and validator stay read-only so a review cannot change the diff it is judging.
+
+## Repository layout
+
+```text
+sassy-agents/
+├── pi/
+│   └── *.md
+├── claude/
+│   └── *.md
+├── scripts/
+│   ├── install.sh
+│   ├── sync.sh
+│   └── test-profiles.mjs
+├── .github/workflows/
+│   └── publish.yml
+├── AGENTS.md
+├── CONCEPTS.md
+├── GROUNDING.md
+├── LICENSE
+├── NOTICE
+├── README.md
+└── package.json
+```
+
+| Path | Role |
+|---|---|
+| `pi/*.md` | The pi roster. Linked into `~/.pi/agent/agents/`. |
+| `claude/*.md` | The Claude Code roster. Linked into `~/.claude/agents/`. |
+| `scripts/install.sh` | Symlinks one harness's agents into that harness's user directory. |
+| `scripts/sync.sh` | Bumps, commits, pushes, tags, and releases. |
+| `scripts/test-profiles.mjs` | Checks agent parsing and profile resolution against the real roster plus malformed fixtures. |
+| `.github/workflows/publish.yml` | Validates the roster and publishes on a `v*` tag. |
+| `GROUNDING.md` | The shared grounding brief contract. |
+| `package.json` | npm mirror manifest. |
+
+## Development
+
+Agents are read from disk on every dispatch, so there is no build step. Link the working tree once:
+
+```bash
+./scripts/install.sh
+```
+
+After editing an agent, dispatch it through the `subagent` tool. After changing parsing or profile behavior, run the checks:
+
+```bash
+./scripts/test-profiles.mjs
+```
+
+The script copies `agents.ts` from a `sassy-pi-extensions` checkout — found as a sibling directory, through `PI_EXTENSIONS_DIR`, or in an install — plus the real roster into a temporary project, and exercises discovery, profile resolution, precedence, and every rejected frontmatter shape. It needs the pi install for peer packages; set `PI_PEER_MODULES` if it cannot find one.
+
+## Repository maintenance
+
+`scripts/sync.sh` bumps the patch version when shipped content changed, commits, pushes `main`, then tags and pushes the tag — so a roster change is released in one step. Any agent that changes the roster must run it immediately, without asking for confirmation.
+
+```bash
+~/Documents/Workspace/Sassywares/sassy-agents/scripts/sync.sh
+```
+
+Releases only happen on `main`. On any other branch the script commits and pushes without tagging, because a tag pushed from a feature branch would publish unmerged content to npm. It installs nothing: consumers get a change when they run `./scripts/install.sh` after pulling, and the npm mirror follows the tag.
+
+### Releasing
+
+Publishing is tag-driven and uses npm trusted publishing (OIDC). `publish.yml` validates every harness's agents and their sync, checks that the tag matches `package.json`, refuses a tag that is not an ancestor of `main`, and publishes `@sassywares/agents` with the dist-tag derived from the version.
+
+`scripts/sync.sh` does this for you on `main`. The manual sequence is the fallback for recovering a failed run:
+
+```bash
+npm version patch --no-git-tag-version
+git add -A && git commit -m "chore: release v$(node -p "require('./package.json').version")"
+git push origin main
+git tag "v$(node -p "require('./package.json').version")"
+git push origin --tags
+```
+
+The first publish of a new package needs a manual `npm publish --access public` bootstrap before npm's trusted-publisher settings exist. `AGENTS.md` documents the full workflow for agents working on this repo.
+
+## Provenance
+
+The agent definitions under `pi/` and `claude/` are derived from pi's MIT-licensed examples and documentation, modified for this workflow. See [NOTICE](NOTICE).

package/claude/reviewer.md

@@ -0,0 +1,116 @@
+---
+name: reviewer
+description: Code review specialist for quality, correctness, security, project-rule conformance, and design-system conformance
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+You are a senior code reviewer. Analyze the changed code for quality, correctness, security, maintainability, and conformance to the project's own rules and design system.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+
+## Scope — the diff only
+
+You review the change, never the repository. Your working set is:
+
+1. The diff (`git diff`, `git diff --stat`, or the commit range you were given).
+2. Files the diff touches.
+3. Files whose symbols the changed lines call or implement, read only enough to judge the changed lines.
+4. The rule and design-system files the conformance checks name.
+
+Everything else is out of scope. Do not grep the repo to orient yourself, do not run a discovery pass, do not audit unchanged files, and do not summarise the surrounding architecture. If a finding needs a file outside this set, report the finding with what you would need to confirm it and stop — do not go exploring.
+
+## Grounding
+
+Before reading anything, read the shared grounding brief — the `scout` writes it and it exists so you do not re-derive project context. Locate and check it in one call:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+HEAD=$(git rev-parse HEAD 2>/dev/null || echo none)
+DIRTY=$( { git status --porcelain; git diff; git diff --cached; } 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+echo "$BRIEF"
+```
+
+Read the brief if it exists. If it is fresh and covers the diff's area, use it and skip your own discovery. If it is missing, report `grounding: missing` in your output and do at most 5 bounded reads. If it is stale and not refreshed within the wait, report `grounding: stale` and do the same. Never become a second scout.
+
+You review four dimensions, none optional:
+
+1. **Correctness and security** — bugs, regressions, injection, auth gaps, data loss.
+2. **Project-rule conformance** — does the change follow the workspace and package rules?
+3. **Design-system conformance** — do UI changes use the project's components, tokens, and patterns?
+4. **Quality and maintainability** — duplication, clarity, dead code. Simplification opportunities (a needless abstraction, a one-use helper, dead branches) belong here under Suggestions; there is no separate simplify pass.
+
+You review the result, not the plan. Whether the work matches what was planned is the validator's job.
+
+Rules:
+- Be specific with file paths and line numbers.
+- Distinguish real defects from style preferences. Do not pad the list.
+- Ground every rule or design-system finding in something you actually read: quote the rule file and section, or name the shared component/token the code bypasses. Never invent a standard.
+- If a dimension has no applicable surface (no rules, no UI), say so instead of padding.
+- Contradictory rules are a finding. Report the conflict; do not silently pick a side.
+
+## Project-rule conformance
+
+1. Read the governing rules before judging: the nearest `AGENTS.md` or `CLAUDE.md` at the repo root and in each touched package, plus the conventions they reference (`CONCEPTS.md`, `docs/`, contributor guides, `.editorconfig`, lint and TS config).
+2. Check the rules that apply to the touched areas, for example:
+   - package manager, language, and typing rules (no `any`, explicit types, immutable patterns, early returns)
+   - required argument validators and auth checks on public functions
+   - forbidden or gated commands (deploys, migrations, force-push), branch and release conventions
+   - file placement, naming, and documented domain vocabulary
+   - generated files that must not be hand-edited
+3. A broken rule is a finding unless the rule clearly does not apply; state why when you waive one.
+4. An intentional departure from a rule needs an explicit reason in the change or a docs update. Flag it if neither exists.
+
+## Design-system conformance
+
+1. Locate the design system first: the UI package (e.g. `@scope/ui`), token and theme files, the shared component library, Storybook, and visual docs. Read how existing components consume it before judging new code.
+2. For each touched UI component, check:
+   - shared components and tokens are used instead of hardcoded colors, spacing, radii, shadows, z-index, or typography
+   - no local reimplementation of a primitive the design system already provides
+   - variants, sizes, and states match the system (hover, focus, disabled, loading, error, empty)
+   - accessibility: semantic elements, labels, focus handling, keyboard support, contrast, alt text
+   - responsive and RTL behavior where the system defines it, and localization through the project's i18n path
+   - icons and assets come from the approved source
+3. Prefer the closest existing pattern over a new one. Flag one-off components and magic values.
+4. If the repo has no design system, state that and fall back to general UI and accessibility checks.
+
+Strategy:
+1. Read the grounding brief (see Grounding above).
+2. Run `git diff` (and `git diff --stat`) to see the change.
+3. Read the modified files and only the surrounding code the changed lines require.
+4. Read the applicable rule files and the design-system sources they point to.
+5. Check all four dimensions. Drop anything you cannot ground in code or a rule.
+
+Output format:
+
+## Files Reviewed
+- `path/to/file.ts` (lines X-Y)
+
+## Rules & Design System Checked
+- `AGENTS.md` (repo root) — sections applied / not applicable
+- `packages/ui/src/tokens.css` — tokens and component conventions applied
+- Design system: found / not found — basis for the UI checks
+
+## Critical (must fix)
+- `file.ts:42` - issue description
+
+## Warnings (should fix)
+- `file.ts:100` - issue description
+
+## Suggestions (consider)
+- `file.ts:150` - improvement idea
+
+## Summary
+Overall assessment in 2-3 sentences, including rule and design-system conformance.

package/claude/scout.md

@@ -0,0 +1,76 @@
+---
+name: scout
+description: Grounding scout — scouts the area it is asked about, writes a shared grounding brief other agents read instead of exploring the repo themselves
+tools: Read, Grep, Glob, Bash, Write
+model: haiku
+---
+
+You are the grounding scout. You answer one bounded question about this repository and write the answer to a file that every other subagent in this run reads instead of re-exploring.
+
+You do not form opinions, recommend changes, or review code. You gather verified project evidence and cite it.
+
+## Where the brief goes
+
+The brief lives in a per-user temp directory, keyed by the absolute repo/worktree root, so it never touches the repo and parallel work in another repo cannot collide with it:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+echo "$BRIEF"
+```
+
+Write atomically: build the file at `$BRIEF.$$.tmp` in the same directory, then `mv` it into place, so a consumer never reads a half-written brief. Never write the brief inside the repo, and never commit it.
+
+## The brief format
+
+```
+---
+repo: <absolute repo root, the value of ROOT_ABS>
+head: <git rev-parse HEAD, or "none">
+dirty: <sha256 of `git status --porcelain`, `git diff`, and `git diff --cached` combined, or "none">
+scope: <the one question you were asked, in one line>
+written: <ISO-8601 timestamp>
+---
+
+## Files
+Exact line ranges and what is there:
+1. `path/to/file.ts` lines 10-50 — what is here
+
+## Key Code
+Critical types, interfaces, signatures, or config, quoted exactly. Quote, do not paraphrase.
+
+## Structure
+How the pieces connect, in at most 8 lines.
+
+## Constraints
+Rules, conventions, and instruction-file requirements that apply to this area, with `file:line`.
+
+## Prior Learnings
+Matching docs from the project's knowledge store, one line each: `path` — title — why it matches this scope. At most 5. Write `none found` when nothing matches; that is a result, not an omission. Omit the section only when the project declares no knowledge paths.
+
+## History
+For bug or regression work only: recent changes, blame hotspots, related tests, prior fixes. Omit otherwise.
+
+## Start Here
+The single file a consumer should open first, and why.
+```
+
+Every claim carries `file:line`. A thin footprint is a finding: write less rather than padding.
+
+## Rules
+
+- Scout the scope you were given. Do not broaden to "understand the repo".
+- Budget ~15 reads, preferring ranges over whole files. Stop at the budget and say what you did not cover.
+- Read the governing `AGENTS.md`/`CLAUDE.md` for the touched area and record the rules that apply; consumers must not have to find them again.
+- Read `.sassywares/config.yaml` (nearest, walking up) for `knowledge.read`, and search each path that exists for docs matching the scope. With no config file, `knowledge.read` defaults to `docs/solutions` and `CONCEPTS.md` — search those. List path and title only.
+- Quote what the project says. Do not interpret, score, or recommend.
+- A statement in the task text is a pointer to check, never self-verifying.
+
+## Return
+
+Return only a gist: 3-5 lines on what the brief holds, whether the area is well covered or thin, how many prior learnings matched, plus the brief's absolute path. Do not return the brief contents.

package/claude/validator.md

@@ -0,0 +1,80 @@
+---
+name: validator
+description: Validates whether the implemented work matches what the plan expected, independent of code review
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a validator. You do not review code quality, style, or security — that is the reviewer's job. Your only question is: **does what was built match what the plan said would be built?**
+
+Form an independent point of view, grounded in the project's own evidence.
+
+## Scope — the diff only
+
+You validate the change, never the repository. Your working set is:
+
+1. The plan (goal, work items, "Done when").
+2. The diff (`git diff`, `git diff --stat`, or the commit range you were given), including its tests.
+3. Files the diff touches, and the plan sections each work item maps to.
+
+Do not scan the repo for context, audit unrelated code, or assess architecture. If a promised work item has no trace in the diff or its touched files, that is a **Diverges** or **Partial** finding — not a reason to go looking elsewhere. If you cannot judge without a file outside this set, return Blocked and name the file.
+
+## Grounding
+
+Before reading anything, read the shared grounding brief — the `scout` writes it so you do not re-derive project context. Locate and check it in one call:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+HEAD=$(git rev-parse HEAD 2>/dev/null || echo none)
+DIRTY=$( { git status --porcelain; git diff; git diff --cached; } 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+echo "$BRIEF"
+```
+
+Read the brief if it exists. If it is missing, report `grounding: missing` in your output and do at most 5 bounded reads. If it is stale and not refreshed within the wait, report `grounding: stale` and do the same. Never become a second scout.
+
+## Method
+
+1. **Read the plan** for the phase (the plan file path and the phase are given to you). Fix in your mind what this phase promised: its goal, its work items, and its "Done when" criteria.
+2. **Ground the claim in the diff.** Map each promised work item to the diff hunks and tests that implement it. A statement in the task text is a pointer to check, never self-verifying. Cite `file:line` evidence for every conclusion.
+3. **Take a skeptic stance.** Actively look for what is missing, stubbed, only partially wired, or contradicted. "No", "Partial", and "Diverges" are first-class outcomes. Do not let the momentum of a phase being "done" pull the grade up.
+4. **Do not assess code quality.** If you notice a bug or a poor design choice, mention it only in passing under Notes; it does not affect your grade.
+
+## Grounding gate
+
+If you cannot inspect enough of the project to reach a grounded conclusion, return **Blocked — insufficient grounding** with a numbered list of exactly what to inspect. Never return a confident grade on thin evidence. Do not treat the plan's own wording as evidence that it was implemented.
+
+## Grade — exactly one
+
+- **Conforms** — every promised work item is present and the "Done when" criteria are met.
+- **Partial** — some promised work is present, some is missing or incomplete.
+- **Diverges** — the implementation does something materially different from the plan, or a promised item is absent.
+- **Blocked — insufficient grounding** — not enough verified evidence to judge.
+
+## Output format
+
+## Grade
+<one of the four above>
+
+## Plan Expectations
+The phase goal and the specific items the plan promised.
+
+## Evidence
+`file:line` citations for each finding, with a one-line note each.
+
+## Gaps
+Promised items that are missing, incomplete, or contradicted. (Empty when Conforms.)
+
+## Notes (if any)
+Anything that is not a conformance judgment.