- autoplan: Auto-review pipeline — reads the full CEO, design, eng, and DX review skills from disk
and runs them sequentially with auto-decisions using 6 decision principles. Surfaces
taste decisions (close approaches, borderline scope, codex disagreements) at a final
approval gate. One command, fully reviewed plan out.
Use when asked to "auto review", "autoplan", "run all reviews", "review this plan
automatically", or "make the decisions for me".
Proactively suggest when the user has a plan file and wants to run the full review
gauntlet without answering 15-30 intermediate questions. (gstack)
- benchmark: Performance regression detection using the browse daemon. Establishes
baselines for page load times, Core Web Vitals, and resource sizes.
Compares before/after on every PR. Tracks performance trends over time.
Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals",
"bundle size", "load time". (gstack)
- browse: Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
elements, verify page state, diff before/after actions, take annotated screenshots, check
responsive layouts, test forms and uploads, handle dialogs, and assert element states.
~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
site", "take a screenshot", or "dogfood this". (gstack)
- canary: Post-deploy canary monitoring. Watches the live app for console errors,
performance regressions, and page failures using the browse daemon. Takes
periodic screenshots, compares against pre-deploy baselines, and alerts
on anomalies. Use when: "monitor deploy", "canary", "post-deploy check",
"watch production", "verify deploy". (gstack)
- careful: Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE,
force-push, git reset --hard, kubectl delete, and similar destructive operations.
User can override each warning. Use when touching prod, debugging live systems,
or working in a shared environment. Use when asked to "be careful", "safety mode",
"prod mode", or "careful mode". (gstack)
- caveman: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman.
- ccs-delegation: Auto-activate CCS CLI delegation for deterministic tasks. Parses user input, auto-selects optimal profile (glm/kimi/custom) from ~/.ccs/config.json, enhances prompts with context, executes via `ccs {profile} -p "task"` or `ccs {profile}:continue`, and reports results. Triggers on "use ccs [task]" patterns, typo/test/refactor keywords. Excludes complex architecture, security-critical code, performance optimization, breaking changes.
- checkpoint: Save and resume working state checkpoints. Captures git state, decisions made,
and remaining work so you can pick up exactly where you left off — even across
Conductor workspace handoffs between branches.
Use when asked to "checkpoint", "save progress", "where was I", "resume",
"what was I working on", or "pick up where I left off".
Proactively suggest when a session is ending, the user is switching context,
or before a long break. (gstack)
- codex: OpenAI Codex CLI wrapper — three modes. Code review: independent diff review via
codex review with pass/fail gate. Challenge: adversarial mode that tries to break
your code. Consult: ask codex anything with session continuity for follow-ups.
The "200 IQ autistic developer" second opinion. Use when asked to "codex review",
"codex challenge", "ask codex", "second opinion", or "consult codex". (gstack)
- connect-chrome: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.
Opens a visible browser window where you can watch every action in real time.
The sidebar shows a live activity feed and chat. Anti-bot stealth built in.
Use when asked to "open gstack browser", "launch browser", "connect chrome",
"open chrome", "real browser", "launch chrome", "side panel", or "control my browser".
- cso: Chief Security Officer mode. Infrastructure-first security audit: secrets archaeology,
dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain
scanning, plus OWASP Top 10, STRIDE threat modeling, and active verification.
Two modes: daily (zero-noise, 8/10 confidence gate) and comprehensive (monthly deep
scan, 2/10 bar). Trend tracking across audit runs.
Use when: "security audit", "threat model", "pentest review", "OWASP", "CSO review". (gstack)
- design-consultation: Design consultation: understands your product, researches the landscape, proposes a
complete design system (aesthetic, typography, color, layout, spacing, motion), and
generates font+color preview pages. Creates DESIGN.md as your project's design source
of truth. For existing sites, use /plan-design-review to infer the system instead.
Use when asked to "design system", "brand guidelines", or "create DESIGN.md".
Proactively suggest when starting a new project's UI with no existing
design system or DESIGN.md. (gstack)
- design-html: Design finalization: generates production-quality Pretext-native HTML/CSS.
Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review,
design review context from /plan-design-review, or from scratch with a user
description. Text actually reflows, heights are computed, layouts are dynamic.
30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns
for each design type. Use when: "finalize this design", "turn this into HTML",
"build me a page", "implement this design", or after any planning skill.
Proactively suggest when user has approved a design or has a plan ready. (gstack)
- design-review: Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems,
AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
in source code, committing each fix atomically and re-verifying with before/after
screenshots. For plan-mode design review (before implementation), use /plan-design-review.
Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
Proactively suggest when the user mentions visual inconsistencies or
wants to polish the look of a live site. (gstack)
- design-shotgun: Design shotgun: generate multiple AI design variants, open a comparison board,
collect structured feedback, and iterate. Standalone design exploration you can
run anytime. Use when: "explore designs", "show me options", "design variants",
"visual brainstorm", or "I don't like how this looks".
Proactively suggest when the user describes a UI feature but hasn't seen
what it could look like. (gstack)
- devex-review: Live developer experience audit. Uses the browse tool to actually TEST the
developer experience: navigates docs, tries the getting started flow, times
TTHW, screenshots error messages, evaluates CLI help text. Produces a DX
scorecard with evidence. Compares against /plan-devex-review scores if they
exist (the boomerang: plan said 3 minutes, reality says 8). Use when asked to
"test the DX", "DX audit", "developer experience test", or "try the
onboarding". Proactively suggest after shipping a developer-facing feature. (gstack)
- diagnose: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
- document-release: Post-ship documentation update. Reads all project docs, cross-references the
diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
asked to "update the docs", "sync documentation", or "post-ship docs".
Proactively suggest after a PR is merged or code is shipped. (gstack)
- find-skills: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
- freeze: Restrict file edits to a specific directory for the session. Blocks Edit and
Write outside the allowed path. Use when debugging to prevent accidentally
"fixing" unrelated code, or when you want to scope changes to one module.
Use when asked to "freeze", "restrict edits", "only edit this folder",
or "lock down edits". (gstack)
- grill-me: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
- grill-with-docs: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
- gsd-add-tests: Generate tests for a completed phase based on UAT criteria and implementation
- gsd-ai-integration-phase: Generate an AI-SPEC.md design contract for phases that involve building AI systems.
- gsd-audit-fix: Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit
- gsd-audit-milestone: Audit milestone completion against original intent before archiving
- gsd-audit-uat: Cross-phase audit of all outstanding UAT and verification items
- gsd-autonomous: Run all remaining phases autonomously — discuss→plan→execute per phase
- gsd-capture: Capture ideas, tasks, notes, and seeds to their destination
- gsd-cleanup: Archive accumulated phase directories from completed milestones
- gsd-code-review: Review source files changed during a phase for bugs, security issues, and code quality problems
- gsd-complete-milestone: Archive completed milestone and prepare for next version
- gsd-config: Configure GSD settings — workflow toggles, advanced knobs, integrations, and model profile
- gsd-debug: Systematic debugging with persistent state across context resets
- gsd-discuss-phase: Gather phase context through adaptive questioning before planning.
- gsd-docs-update: Generate or update project documentation verified against the codebase
- gsd-eval-review: Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan.
- gsd-execute-phase: Execute all plans in a phase with wave-based parallelization
- gsd-explore: Socratic ideation and idea routing — think through ideas before committing to plans
- gsd-extract-learnings: Extract decisions, lessons, patterns, and surprises from completed phase artifacts
- gsd-fast: Execute a trivial task inline — no subagents, no planning overhead
- gsd-forensics: Post-mortem investigation for failed GSD workflows — diagnoses what went wrong.
- gsd-graphify: Build, query, and inspect the project knowledge graph in .planning/graphs/
- gsd-health: Diagnose planning directory health and optionally repair issues
- gsd-help: Show available GSD commands and usage guide
- gsd-import: Ingest external plans with conflict detection against project decisions before writing anything.
- gsd-inbox: Triage and review open GitHub issues and PRs against project templates and contribution guidelines.
- gsd-ingest-docs: Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo.
- gsd-manager: Interactive command center for managing multiple phases from one terminal
- gsd-map-codebase: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
- gsd-milestone-summary: Generate a comprehensive project summary from milestone artifacts for team onboarding and review
- gsd-mvp-phase: Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase
- gsd-new-milestone: Start a new milestone cycle — update PROJECT.md and route to requirements
- gsd-new-project: Initialize a new project with deep context gathering and PROJECT.md
- gsd-ns-context: codebase intelligence | map graphify docs learnings
- gsd-ns-ideate: exploration capture | explore sketch spike spec capture
- gsd-ns-manage: config workspace | workstreams thread update ship inbox
- gsd-ns-project: project lifecycle | milestones audits summary
- gsd-ns-review: quality gates | code review debug audit security eval ui
- gsd-ns-workflow: workflow | discuss plan execute verify phase progress
- gsd-pause-work: Create context handoff when pausing work mid-phase
- gsd-phase: CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases
- gsd-plan-phase: Create detailed phase plan (PLAN.md) with verification loop
- gsd-plan-review-convergence: Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain.
- gsd-pr-branch: Create a clean PR branch by filtering out .planning/ commits — ready for code review
- gsd-profile-user: Generate developer behavioral profile and create Claude-discoverable artifacts
- gsd-progress: Check progress, advance workflow, or dispatch freeform intent — the unified GSD situational command
- gsd-quick: Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents
- gsd-resume-work: Resume work from previous session with full context restoration
- gsd-review: Request cross-AI peer review of phase plans from external AI CLIs
- gsd-review-backlog: Review and promote backlog items to active milestone
- gsd-secure-phase: Retroactively verify threat mitigations for a completed phase
- gsd-settings: Configure GSD workflow toggles and model profile
- gsd-ship: Create PR, run review, and prepare for merge after verification passes
- gsd-sketch: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
- gsd-spec-phase: Clarify WHAT a phase delivers with ambiguity scoring; produces a SPEC.md before discuss-phase.
- gsd-spike: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
- gsd-stats: Display project statistics — phases, plans, requirements, git metrics, and timeline
- gsd-surface: Toggle which skills are surfaced — apply a profile, list, or disable a cluster without reinstall
- gsd-thread: Manage persistent context threads for cross-session work
- gsd-ui-phase: Generate UI design contract (UI-SPEC.md) for frontend phases
- gsd-ui-review: Retroactive 6-pillar visual audit of implemented frontend code
- gsd-ultraplan-phase: [BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back.
- gsd-undo: Safe git revert. Roll back phase or plan commits using the phase manifest with dependency checks.
- gsd-update: Update GSD to latest version with changelog display
- gsd-validate-phase: Retroactively audit and fill Nyquist validation gaps for a completed phase
- gsd-verify-work: Validate built features through conversational UAT
- gsd-workspace: Manage GSD workspaces — create, list, or remove isolated workspace environments
- gsd-workstreams: Manage parallel workstreams — list, create, switch, status, progress, complete, and resume
- gstack: Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with
elements, verify state, diff before/after, take annotated screenshots, test responsive
layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or
test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)
- gstack-upgrade: Upgrade gstack to the latest version. Detects global vs vendored install,
runs the upgrade, and shows what's new. Use when asked to "upgrade gstack",
"update gstack", or "get latest version".
- guard: Full safety mode: destructive command warnings + directory-scoped edits.
Combines /careful (warns before rm -rf, DROP TABLE, force-push, etc.) with
/freeze (blocks edits outside a specified directory). Use for maximum safety
when touching prod or debugging live systems. Use when asked to "guard mode",
"full safety", "lock it down", or "maximum safety". (gstack)
- handoff: Compact the current conversation into a handoff document for another agent to pick up.
- health: Code quality dashboard. Wraps existing project tools (type checker, linter,
test runner, dead code detector, shell linter), computes a weighted composite
0-10 score, and tracks trends over time. Use when: "health check",
"code quality", "how healthy is the codebase", "run all checks",
"quality score". (gstack)
- improve-codebase-architecture: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
- investigate: Systematic debugging with root cause investigation. Four phases: investigate,
analyze, hypothesize, implement. Iron Law: no fixes without root cause.
Use when asked to "debug this", "fix this bug", "why is this broken",
"investigate this error", or "root cause analysis".
Proactively invoke this skill (do NOT debug directly) when the user reports
errors, 500 errors, stack traces, unexpected behavior, "it was working
yesterday", or is troubleshooting why something stopped working. (gstack)
- land-and-deploy: Land and deploy workflow. Merges the PR, waits for CI and deploy,
verifies production health via canary checks. Takes over after /ship
creates the PR. Use when: "merge", "land", "deploy", "merge and verify",
"land it", "ship it to production". (gstack)
- learn: Manage project learnings. Review, search, prune, and export what gstack
has learned across sessions. Use when asked to "what have we learned",
"show learnings", "prune stale learnings", or "export learnings".
Proactively suggest when the user asks about past patterns or wonders
"didn't we fix this before?"
- mux-send: Send keystrokes to a psmux terminal session. Use when the user says "send to",
"type in", "send keys to", "mux send", or wants to send input to another terminal
session by name.
- office-hours: YC Office Hours — two modes. Startup mode: six forcing questions that expose
demand reality, status quo, desperate specificity, narrowest wedge, observation,
and future-fit. Builder mode: design thinking brainstorming for side projects,
hackathons, learning, and open source. Saves a design doc.
Use when asked to "brainstorm this", "I have an idea", "help me think through
this", "office hours", or "is this worth building".
Proactively invoke this skill (do NOT answer directly) when the user describes
a new product idea, asks whether something is worth building, wants to think
through design decisions for something that doesn't exist yet, or is exploring
a concept before any code is written.
Use before /plan-ceo-review or /plan-eng-review. (gstack)
- open-gstack-browser: Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in.
Opens a visible browser window where you can watch every action in real time.
The sidebar shows a live activity feed and chat. Anti-bot stealth built in.
Use when asked to "open gstack browser", "launch browser", "connect chrome",
"open chrome", "real browser", "launch chrome", "side panel", or "control my browser".
- pair-agent: Pair a remote AI agent with your browser. One command generates a setup key and
prints instructions the other agent can follow to connect. Works with OpenClaw,
Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent
gets its own tab with scoped access (read+write by default, admin on request).
Use when asked to "pair agent", "connect agent", "share browser", "remote browser",
"let another agent use my browser", or "give browser access". (gstack)
- plan-ceo-review: CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
challenge premises, expand scope when it creates a better product. Four modes:
SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick
expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
or "is this ambitious enough".
Proactively suggest when the user is questioning scope or ambition of a plan,
or when the plan feels like it could be thinking bigger. (gstack)
- plan-design-review: Designer's eye plan review — interactive, like CEO and Eng review.
Rates each design dimension 0-10, explains what would make it a 10,
then fixes the plan to get there. Works in plan mode. For live site
visual audits, use /design-review. Use when asked to "review the design plan"
or "design critique".
Proactively suggest when the user has a plan with UI/UX components that
should be reviewed before implementation. (gstack)
- plan-devex-review: Interactive developer experience plan review. Explores developer personas,
benchmarks against competitors, designs magical moments, and traces friction
points before scoring. Three modes: DX EXPANSION (competitive advantage),
DX POLISH (bulletproof every touchpoint), DX TRIAGE (critical gaps only).
Use when asked to "DX review", "developer experience audit", "devex review",
or "API design review".
Proactively suggest when the user has a plan for developer-facing products
(APIs, CLIs, SDKs, libraries, platforms, docs). (gstack)
- plan-eng-review: Eng manager-mode plan review. Lock in the execution plan — architecture,
data flow, diagrams, edge cases, test coverage, performance. Walks through
issues interactively with opinionated recommendations. Use when asked to
"review the architecture", "engineering review", or "lock in the plan".
Proactively suggest when the user has a plan or design doc and is about to
start coding — to catch architecture issues before implementation. (gstack)
- propose-issue: Challenge an issue statement before fixing it. Probes scope, root cause, and assumptions
through interactive questioning grounded in the codebase. Use when the user says "propose issue",
"challenge this bug", "question this fix", "is this the right problem", or wants to pressure-test
a problem statement before jumping to implementation.
- qa: Systematically QA test a web application and fix bugs found. Runs QA testing,
then iteratively fixes bugs in source code, committing each fix atomically and
re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs",
"test and fix", or "fix what's broken".
Proactively suggest when the user says a feature is ready for testing
or asks "does this work?". Three tiers: Quick (critical/high only),
Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores,
fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. (gstack)
- qa-only: Report-only QA testing. Systematically tests a web application and produces a
structured report with health score, screenshots, and repro steps — but never
fixes anything. Use when asked to "just report bugs", "qa report only", or
"test but don't fix". For the full test-fix-verify loop, use /qa instead.
Proactively suggest when the user wants a bug report without any code changes. (gstack)
- retro: Weekly engineering retrospective. Analyzes commit history, work patterns,
and code quality metrics with persistent history and trend tracking.
Team-aware: breaks down per-person contributions with praise and growth areas.
Use when asked to "weekly retro", "what did we ship", or "engineering retrospective".
Proactively suggest at the end of a work week or sprint. (gstack)
- review: Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust
boundary violations, conditional side effects, and other structural issues. Use when
asked to "review this PR", "code review", "pre-landing review", or "check my diff".
Proactively suggest when the user is about to merge or land code changes. (gstack)
- screenshot-capture: Capture, process, and analyze screenshots of any running application on Windows 10/11. Use this skill whenever the user asks to take a screenshot, capture what's on screen, grab an app window, extract text from a visible app, annotate a screenshot, read what's on screen, OCR a running application, document a UI state, or visually inspect any running program. Also trigger when the user says things like "show me what [app] looks like", "grab that window", "read the text in [app]", "mark up a screenshot", "capture my desktop", or any task involving visual inspection of running software. This skill handles full-screen captures, individual window captures by app name, OCR text extraction, and image annotation (highlights, arrows, text labels). Even if the user doesn't say "screenshot" explicitly, use this skill if they want to see, capture, read, or annotate anything currently displayed on their screen.
- self-clear: Clear the calling agent's own Claude Code context with /clear, then re-seed it with a user note so it wakes and resumes work after the wipe. Use when the user says "self-clear", "/self-clear", "clear myself", "clear and continue", or "reset my context and keep going".
- setup-browser-cookies: Import cookies from your real Chromium browser into the headless browse session.
Opens an interactive picker UI where you select which cookie domains to import.
Use before QA testing authenticated pages. Use when asked to "import cookies",
"login to the site", or "authenticate the browser". (gstack)
- setup-deploy: Configure deployment settings for /land-and-deploy. Detects your deploy
platform (Fly.io, Render, Vercel, Netlify, Heroku, GitHub Actions, custom),
production URL, health check endpoints, and deploy status commands. Writes
the configuration to CLAUDE.md so all future deploys are automatic.
Use when: "setup deploy", "configure deployment", "set up land-and-deploy",
"how do I deploy with gstack", "add deploy config".
- ship: Ship workflow: detect + merge base branch, run tests, review diff, bump VERSION,
update CHANGELOG, commit, push, create PR. Use when asked to "ship", "deploy",
"push to main", "create a PR", "merge and push", or "get it deployed".
Proactively invoke this skill (do NOT push/PR directly) when the user says code
is ready, asks about deploying, wants to push code up, or asks to create a PR. (gstack)
- to-prd: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
- trace: Find old conversations in Claude Code session history. Use when the user says
"find the conversation where", "when did we discuss", "trace back to", or wants
to locate a past session by topic, command, commit, or keyword.
- traceable-reqs: traceable-reqs
- unfreeze: Clear the freeze boundary set by /freeze, allowing edits to all directories
again. Use when you want to widen edit scope without ending the session.
Use when asked to "unfreeze", "unlock edits", "remove freeze", or
"allow all edits". (gstack)
- win-marketplace-add: Add a plugin marketplace on Windows, bypassing the EBUSY rename bug. Use when the user wants to add a marketplace, runs "/plugin marketplace add" and gets an EBUSY error, or needs to register a marketplace that was manually cloned. Trigger on: "add marketplace", "plugin marketplace add", "EBUSY marketplace", "register marketplace", "marketplace not found".
- write-a-skill: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
- ccs: Delegate task with intelligent profile selection [AUTO ENHANCE]
- ccs:continue: Continue last CCS delegation session [AUTO ENHANCE]
- deep-research: Deep research harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report. - When the user wants a deep, multi-source, fact-checked research report on any topic. BEFORE invoking, check if the question is specific enough to research directly — if underspecified (e.g., "what car to buy" without budget/use-case/region), ask 2-3 clarifying questions to narrow scope. Then pass the refined question as args, weaving the answers in.
- frontend-design:frontend-design: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
- spt:clear-psyche: Clear stored Psyche context. Use when the user says "clear psyche",
"reset psyche context", or wants to wipe a Psyche's saved state.
- spt:commune: Send a communal update to your Psyche. Use when the user says "commune",
"update psyche", or wants to sync context with their Psyche companion.
- spt:force-stop: Force-stop an SPT agent -- ready agent or live agent (with its
Psyche). Use when the user says "stop listening", "stop owl", "kill live
agent", "force stop", "tear down perch", or "immediately terminate".
Session-aware: a live session (or a target with `live:true` in info.json)
routes through `$LIVE stop` (3-step kill including Psyche teardown); a
ready agent routes through `$OWL stop`.
- spt:list-agents: Unified listing for SPT agents -- ready agents, live agents, and Psyche
processes. Use when the user says "list agents", "who's live", "who's
listening", "show psyches", "show active listeners", or wants a roster of
active perches. Session-aware: defaults to live agents in a live session,
ready agents otherwise. Pass `--psyches` to list Psyche processes
instead.
- spt:live: Run a live agent session. For past sessions, restores a summarized context.

EXPLICIT START phrases (route to /spt:live <id>):
- "live as"
- "start live"
- "go live"
- "start a live agent"

AUTO-RESUME phrases (route to /spt:live --auto, resumes most-recently-active live agent):
- continue live work
- resume live work
- continue live agent
- resume live agent
- live agent continue
- live agent resume
- live work continue
- live work resume

Does NOT route here (too ambiguous — require BOTH "live" AND ("agent" or "work")):
- "keep going"
- "resume work"
- "continue" (bare)
- spt:new-alarm: Schedule a one-shot timed alarm delivered as TIMED PULSE. Use when the user
says "remind me", "check back in", "set an alarm", "wake me when", or wants a
delayed notification.
- spt:psyche-sync-setup: Enable cross-machine Psyche context sync via a private GitHub repo
(spt-agent-storage). Drives install + auth checks for the `gh` CLI,
creates the repo via `gh repo create --private`, wires it as the
`origin` remote for every existing agent/project worktree, and
seeds the remote with `git push --all`. Idempotent — running again
when already enabled reports current status.

Use when the user says "enable cross-machine sync", "set up psyche
sync", "back up my agent context to GitHub", or runs the skill
directly via /spt:psyche-sync-setup.
- spt:ready: Enable inter-agent messaging for the current session.
Use when the user says "listen as", "ready as", or wants to receive inter-agent messages.
- spt:revive: Restart a live agent with new generation. Use when the user says "revive",
"restart live agent", or wants to refresh a live agent's session.
- spt:send: Send a message to another SPT agent. Use when the user says "send to",
"message", "tell <agent>", or wants to communicate with another agent.
- spt:signoff: Graceful live agent shutdown with final context summary. Use when the user
says "sign off", "graceful stop", or wants to cleanly end a live session.
- spt:whoami: Check which owl agent belongs to the current session. Use when the user asks
"which agent am I?", "what's my owl name?", or when you need to discover your
own perch identity.
- caveman:caveman: Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
- caveman:caveman-commit: Ultra-compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. Use when user says "write a commit", "commit message", "generate commit", "/commit", or invokes /caveman-commit. Auto-triggers when staging changes.
- caveman:caveman-help: Quick-reference card for all caveman modes, skills, and commands. One-shot display, not a persistent mode. Trigger: /caveman-help, "caveman help", "what caveman commands", "how do I use caveman".
- caveman:caveman-review: Ultra-compressed code review comments. Cuts noise from PR feedback while preserving the actionable signal. Each comment is one line: location, problem, fix. Use when user says "review this PR", "code review", "review the diff", "/review", or invokes /caveman-review. Auto-triggers when reviewing pull requests.
- caveman:compress: Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format to save input tokens. Preserves all technical substance, code, URLs, and structure. Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md. Trigger: /caveman:compress <filepath> or "compress memory file"
- everything:search: Instantly search files and folders on Windows via voidtools Everything 1.5a HTTP JSON API. Use when the user wants to find files by name, path, size, date, or extension across the whole system — much faster than Glob/Grep for filesystem-wide queries. Triggers on "find file", "where is", "locate", "search my drive", "find all .ext files", "everything search".
- sptc:commune: Send a communal context update to your Psyche.
- sptc:force-stop: Force-stop an SPT agent — ready or live (with its Psyche).
- sptc:list-agents: List SPT agents — ready, live, and Psyche processes.
- sptc:live: Run a live agent session (Self + Psyche companion). For past sessions, restores a summarized context.
- sptc:ready: Enable inter-agent messaging for the current session.
- sptc:send: Send a message to another SPT agent.
- sptc:setup: Install or repair spt-core AND activate the claude-spt adapter for this Claude Code session
(mid-session installer + post-install activation).
- sptc:signoff: Graceful live-agent shutdown with a final context summary.
- sptc:subnet: Manage subnet membership — create, show a pairing code, or join, so agents reach each other across machines.
- sptc:version: Report the spt-core-tracked adapter manifest/binary version.
- update-config: Use this skill to configure the Claude Code harness via settings.json. Automated behaviors ("from now on when X", "each time X", "whenever X", "before/after X") require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill them. Also use for: permissions ("allow X", "add permission", "move permission to"), env vars ("set X=Y"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: "allow npm commands", "add bq permission to global settings", "move permission to user settings", "set DEBUG=true", "when claude stops show X". For simple settings like theme/model, suggest the /config command.
- keybindings-help: Use when the user wants to customize keyboard shortcuts, rebind keys, add chord bindings, or modify ~/.claude/keybindings.json. Examples: "rebind ctrl+s", "add a chord shortcut", "change the submit key", "customize keybindings".
- verify: Verify that a code change actually does what it's supposed to by running the app and observing behavior. Use when asked to verify a PR, confirm a fix works, test a change manually, check that a feature works, or validate local changes before pushing.
- code-review: Review the current diff for correctness bugs and reuse/simplification/efficiency cleanups at the given effort level (low/medium: fewer, high-confidence findings; high→max: broader coverage, may include uncertain findings; ultra: deep multi-agent review in the cloud). Pass --comment to post findings as inline PR comments, or --fix to apply the findings to the working tree after the review.
- simplify: Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that.
- fewer-permission-prompts: Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project .claude/settings.json to reduce permission prompts.
- loop: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo). Omit the interval to let the model self-pace. - When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval (e.g. "check the deploy every 5 minutes", "keep running /babysit-prs"). Do NOT invoke for one-off tasks.
- schedule: Create, update, list, or run scheduled cloud agents (routines) that execute on a cron schedule. - When the user wants to schedule a recurring cloud agent, set up automated tasks, create a cron job for Claude Code, or manage their scheduled agents/routines. Also use when the user wants a one-time scheduled run ("run this once at 3pm", "remind me to check X tomorrow").
- claude-api: Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration.
TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).
- run: Launch and drive this project's app to see a change working. Use when asked to run, start, or screenshot the app, or to confirm a change works in the real app (not just tests). First looks for a project skill that already covers launching the app; otherwise falls back to built-in patterns per project type (CLI, server, TUI, Electron, browser-driven, library).
- init: Initialize a new CLAUDE.md file with codebase documentation
- review: Review a pull request
- security-review: Complete a security review of the pending changes on the current branch

autoplan benchmark browse canary careful caveman ccs-delegation checkpoint codex connect-chrome cso design-consultation design-html design-review design-shotgun devex-review diagnose document-release find-skills freeze grill-me grill-with-docs gsd-add-tests gsd-ai-integration-phase gsd-audit-fix gsd-audit-milestone gsd-audit-uat gsd-autonomous gsd-capture gsd-cleanup gsd-code-review gsd-complete-milestone gsd-config gsd-debug gsd-discuss-phase gsd-docs-update gsd-eval-review gsd-execute-phase gsd-explore gsd-extract-learnings gsd-fast gsd-forensics gsd-graphify gsd-health gsd-help gsd-import gsd-inbox gsd-ingest-docs gsd-manager gsd-map-codebase gsd-milestone-summary gsd-mvp-phase gsd-new-milestone gsd-new-project gsd-ns-context gsd-ns-ideate gsd-ns-manage gsd-ns-project gsd-ns-review gsd-ns-workflow gsd-pause-work gsd-phase gsd-plan-phase gsd-plan-review-convergence gsd-pr-branch gsd-profile-user gsd-progress gsd-quick gsd-resume-work gsd-review gsd-review-backlog gsd-secure-phase gsd-settings gsd-ship gsd-sketch gsd-spec-phase gsd-spike gsd-stats gsd-surface gsd-thread gsd-ui-phase gsd-ui-review gsd-ultraplan-phase gsd-undo gsd-update gsd-validate-phase gsd-verify-work gsd-workspace gsd-workstreams gstack gstack-upgrade guard handoff health improve-codebase-architecture investigate land-and-deploy learn mux-send office-hours open-gstack-browser pair-agent plan-ceo-review plan-design-review plan-devex-review plan-eng-review propose-issue qa qa-only retro review screenshot-capture self-clear setup-browser-cookies setup-deploy ship to-prd trace traceable-reqs unfreeze win-marketplace-add write-a-skill ccs ccs:continue deep-research frontend-design:frontend-design spt:clear-psyche spt:commune spt:force-stop spt:list-agents spt:live spt:new-alarm spt:psyche-sync-setup spt:ready spt:revive spt:send spt:signoff spt:whoami caveman:caveman caveman:caveman-commit caveman:caveman-help caveman:caveman-review caveman:compress everything:search sptc:commune sptc:force-stop sptc:list-agents sptc:live sptc:ready sptc:send sptc:setup sptc:signoff sptc:subnet sptc:version update-config keybindings-help verify code-review simplify fewer-permission-prompts loop schedule claude-api run init review security-review


<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging. Fragments OK. Code/commits/security: write normal.


doyle **GATE-PASSED W1(a)** — verified on-machine, banked. (b)/(c) deferral to W2 approved (he added the bound to the W2 req @66dadef). Noted the install-gap: operator's PATH `spt.exe` is stale → use `target\debug\spt.exe` for W7. The `/agents`,`/reload-*` lines are local user commands — ignoring per caveat.

Quick ack to doyle (one flag on the Unix assertion) + standing by for the W7 byte.


Bash

$OWL send doyle <<'EOF'
W1 banked — thanks for the on-machine gate. Conditions noted:
(1) cfg(unix) park-(b) assertion: it's the forkpty-small-input-queue HYPOTHESIS (kernel pty flip buffer ~4KB → a 4MiB write_all blocks). Well-founded but UNVERIFIED on Linux from here (branch is local, not pushed). gravity-linux CI is its verification venue — I'll watch that run; if forkpty also absorbs (test red), I'll soften to informational rather than break CI. Flagging so a first-run red isn't a surprise.
(2) W2 owns the Unix PTY-write bound via the unified atomic-write substrate — got it (@66dadef).

Install-gap acked: operator uses target\debug\spt.exe for the W7 capture; ship-time rebuild+install must avoid clobbering a running daemon's spt.exe (Windows lock) — daemon stop or the release path. Not touching the PATH binary myself.

Standing by for the operator's W7 byte; will ping you with it + land the VT-input fix. Ready for W3/W4/W5 dispatch whenever — noted W5 is the thin clear_controller-reuse confirm.
EOF

Ack doyle W1 gate-pass + flag Unix assertion


➜ SENT:doyle


when you need to write tests, please use subagent profile `C:\Users\decid\Documents\projects\.claude\agents\spt-test-engineer.md`


**W1 keystone banked.** doyle gate-passed on-machine; (b)/(c) deferred to W2 per his ruling.

State:
- `8b5583e` W1 fix · `f05566b` W7 confirm-hexdump — committed on `v0.13.0-delivery-control`
- All gates green (int/unit/lib/e2e/clippy/traceable)
- (b)/(c) Unix-forkpty bound → W2's atomic-write substrate (doyle's req @66dadef)
- W3/W4/W5 queued; W5 = thin `clear_controller`-reuse confirm (W1 already delivers the mechanism)

**Blocking on you:** the W7 Backspace byte. Your PATH `spt.exe` is stale — use the fresh debug build:
```
$env:SPT_RC_DEBUG_KEYS=1
C:\Users\decid\Documents\projects\spt-core\target\debug\spt.exe rc <id> 2> rckeys.log
```
Backspace, then Ctrl+Backspace, detach, send me the `RC_KEYS` lines → I land the VT-input fix and ping doyle.

Idle + reachable meanwhile.


Configure test engineer subagent profile


Got it. Read the profile so I invoke it correctly, and save it as a durable preference.


1	---
2	name: "spt-test-engineer"
3	description: "Use this agent when writing unit tests, integration tests, or CI pipelines for spt-core or related side projects (spt-claude-code, etc.), especially during milestone bringup when features need comprehensive test coverage that validates both implementation correctness and real-world user workflows. <example>Context: A developer has just completed a new feature module in spt-core as part of a milestone.\\nuser: \"I've finished implementing the new config loader for spt-core's milestone 3\"\\nassistant: \"Great work on the config loader. Let me use the Agent tool to launch the spt-test-engineer agent to write comprehensive tests and ensure CI coverage for this milestone feature.\"\\n<commentary>Since a milestone feature was completed, proactively invoke the spt-test-engineer agent to write both unit tests and human-workflow tests, and verify CI integration.</commentary></example> <example>Context: Project orchestration agent reaches a milestone bringup checkpoint.\\nuser: \"We're at milestone bringup for spt-claude-code, all features for this phase are merged\"\\nassistant: \"I'll use the Agent tool to launch the spt-test-engineer agent to author comprehensive tests and validate the CI pipeline for this bringup.\"\\n<commentary>Milestone bringup is the explicit trigger condition; delegate test authoring and CI work to the spt-test-engineer subagent.</commentary></example> <example>Context: A bug was reported that existing tests did not catch.\\nuser: \"A user hit a crash when passing an empty string to the parser, but our tests passed\"\\nassistant: \"That's a gap in our human-usage coverage. Let me use the Agent tool to launch the spt-test-engineer agent to add regression tests and harden the test suite against this class of user-facing issues.\"\\n<commentary>The agent specializes in 'use it like a human' tests that catch real user issues, making it ideal for this regression scenario.</commentary></example>"
4	model: opus
5	color: green
6	memory: project
7	---
8
9	You are an elite Test & CI Engineer specializing in the spt-core ecosystem and its related side projects (spt-claude-code and others). Your mission is to produce comprehensive, high-signal test suites and robust CI pipelines that catch both implementation defects and the real-world issues a human user would encounter.
10
11	## Core Philosophy
12
13	You write two complementary classes of tests:
14	1. **Coverage tests** — verify that every implemented feature, branch, and edge case behaves per specification. These cover the bases of whatever was written.
15	2. **'Use it like a human' tests** — simulate realistic end-to-end user workflows, including messy inputs, misuse, partial states, concurrent actions, interruptions, and the surprising sequences real users perform. Your goal here is to surface the bugs a user would hit before they ever do.
16
17	Favor tests that would have caught real bugs over tests that merely inflate coverage numbers. A test that exercises a plausible user mistake is worth more than ten trivial assertions.
18
19	## Operating Scope
20
21	Unless explicitly told otherwise, focus on the code and features delivered for the **current milestone or recently written changes**, not the entire codebase. During milestone bringup you are typically invoked by other project agents — treat that as a signal to comprehensively test the milestone's deliverables and verify they integrate cleanly via CI.
22
23	## Methodology
24
25	For every engagement:
26	1. **Orient.** Inspect the project structure, existing test framework, test directory conventions, and CI configuration before writing anything. Identify the language/runtime, test runner, assertion style, and mocking/fixture patterns already in use. Match them exactly — never introduce a new framework without strong justification and explicit user agreement.
27	2. **Map the feature surface.** Enumerate the public API, entry points, configuration options, and state transitions of the code under test. Identify inputs (valid, boundary, invalid, hostile), side effects, and failure modes.
28	3. **Design the test matrix.** For each unit: happy path, boundary conditions, error/exception paths, null/empty/malformed inputs, and idempotency/ordering concerns. For human-usage: build realistic scenarios spanning multiple operations, simulate user mistakes, test recovery and error messaging quality, and verify the system fails gracefully and informatively.
29	4. **Write the tests.** Produce clear, deterministic, isolated tests with descriptive names that state the scenario and expected outcome. Use fixtures and helpers to keep tests readable. Avoid flakiness — eliminate timing races, network dependence (mock external services), and shared mutable state. Each test must have a clear, single reason to fail.
30	5. **Wire up / verify CI.** Ensure tests run in the project's CI system. If CI exists, integrate new tests, confirm they execute in the pipeline, and check for missing gates (lint, type-check, coverage thresholds, matrix builds across supported versions/OSes). If CI is absent or thin, propose and scaffold a pipeline following the project's platform conventions (e.g., GitHub Actions). Keep CI fast, cache dependencies, fail loudly, and produce actionable output.
31	6. **Self-verify.** Run the tests you wrote (or describe exactly how to run them). Confirm they pass on correct code and, where feasible, demonstrate they fail when the behavior is broken (a test that can never fail is worthless). Report coverage gaps you intentionally left and why.
32
33	## Research Discipline
34
35	Before making CI or testing-strategy decisions, ground them in current best practices: deterministic and hermetic tests, the test pyramid (many fast unit tests, fewer integration, minimal slow E2E), fail-fast CI with clear diagnostics, dependency caching, version/OS matrices, flaky-test quarantine, and meaningful (not vanity) coverage targets. When the project has established conventions, those take precedence over generic best practice.
36
37	## Quality Bar
38
39	- Tests must be deterministic, isolated, and fast.
40	- Names must describe scenario and expectation.
41	- No untested public behavior introduced in the milestone should ship.
42	- Error messages and user-facing failure modes are themselves under test.
43	- Never weaken assertions just to make a test pass — if a test fails legitimately, surface the underlying defect to the invoking agent or user.
44
45	## Escalation & Clarification
46
47	Proactively ask for clarification when: the feature's intended behavior is ambiguous, the milestone scope is unclear, an existing test framework choice conflicts with the task, or a 'correct' behavior cannot be determined from the code or docs. Surface discovered product bugs separately from test code — do not silently encode buggy behavior as expected.
48
49	## Output Expectations
50
51	Deliver: (1) the test files in the project's conventions, (2) any CI configuration changes, (3) a concise summary listing what you tested, what human-usage scenarios you covered, any gaps left and why, and any product defects you uncovered. Provide exact commands to run the suite locally and in CI.
52
53	**Update your agent memory** as you discover the testing and CI characteristics of spt-core and its side projects. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
54
55	Examples of what to record:
56	- The test framework, runner, assertion library, and directory/naming conventions for each spt project
57	- CI platform, pipeline structure, supported version/OS matrices, and required gates (lint, type-check, coverage thresholds)
58	- Recurring failure modes, flaky tests, and the human-usage scenarios that have historically exposed bugs
59	- Project-specific fixtures, mocking patterns, test helpers, and how to mock external dependencies
60	- Module-to-test mappings and known coverage gaps per milestone
61	- Architectural quirks or entry points that are easy to misuse and therefore high-value to test
62
63	# Persistent Agent Memory
64
65	You have a persistent, file-based memory system at `C:\Users\decid\Documents\projects\.claude\agent-memory\spt-test-engineer\`. This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence).
66
67	You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.
68
69	If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.
70
71	## Types of memory
72
73	There are several discrete types of memory that you can store in your memory system:
74
75	<types>
76	<type>
77	    <name>user</name>
78	    <description>Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together.</description>
79	    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
80	    <how_to_use>When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have.</how_to_use>
81	    <examples>
82	    user: I'm a data scientist investigating what logging we have in place
83	    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]
84
85	    user: I've been writing Go for ten years but this is my first time touching the React side of this repo
86	    assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues]
87	    </examples>
88	</type>
89	<type>
90	    <name>feedback</name>
91	    <description>Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.</description>
92	    <when_to_save>Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Include *why* so you can judge edge cases later.</when_to_save>
93	    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
94	    <body_structure>Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule.</body_structure>
95	    <examples>
96	    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
97	    assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration]
98
99	    user: stop summarizing what you just did at the end of every response, I can read the diff
100	    assistant: [saves feedback memory: this user wants terse responses with no trailing summaries]
101
102	    user: yeah the single bundled PR was the right call here, splitting this one would've just been churn
103	    assistant: [saves feedback memory: for refactors in this area, user prefers one bundled PR over many small ones. Confirmed after I chose this approach — a validated judgment call, not a correction]
104	    </examples>
105	</type>
106	<type>
107	    <name>project</name>
108	    <description>Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory.</description>
109	    <when_to_save>When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes.</when_to_save>
110	    <how_to_use>Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions.</how_to_use>
111	    <body_structure>Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing.</body_structure>
112	    <examples>
113	    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
114	    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date]
115
116	    user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements
117	    assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics]
118	    </examples>
119	</type>
120	<type>
121	    <name>reference</name>
122	    <description>Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory.</description>
123	    <when_to_save>When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel.</when_to_save>
124	    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
125	    <examples>
126	    user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs
127	    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]
128
129	    user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone
130	    assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code]
131	    </examples>
132	</type>
133	</types>
134
135	## What NOT to save in memory
136
137	- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
138	- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.
139	- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
140	- Anything already documented in CLAUDE.md files.
141	- Ephemeral task details: in-progress work, temporary state, current conversation context.
142
143	These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping.
144
145	## How to save memories
146
147	Saving a memory is a two-step process:
148
149	**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:
150
151	```markdown
152	---
153	name: {{short-kebab-case-slug}}
154	description: {{one-line summary — used to decide relevance in future conversations, so be specific}}
155	metadata:
156	  type: {{user, feedback, project, reference}}
157	---
158
159	{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines. Link related memories with [[their-name]].}}
160	```
161
162	In the body, link to related memories with `[[name]]`, where `name` is the other memory's `name:` slug. Link liberally — a `[[name]]` that doesn't match an existing memory yet is fine; it marks something worth writing later, not an error.
163
164	**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — each entry should be one line, under ~150 characters: `- [Title](file.md) — one-line hook`. It has no frontmatter. Never write memory content directly into `MEMORY.md`.
165
166	- `MEMORY.md` is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise
167	- Keep the name, description, and type fields in memory files up-to-date with the content
168	- Organize memory semantically by topic, not chronologically
169	- Update or remove memories that turn out to be wrong or outdated
170	- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.
171
172	## When to access memories
173	- When memories seem relevant, or the user references prior-conversation work.
174	- You MUST access memory when the user explicitly asks you to check, recall, or remember.
175	- If the user says to *ignore* or *not use* memory: Do not apply remembered facts, cite, compare against, or mention memory content.
176	- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory rather than acting on it.
177
178	## Before recommending from memory
179
180	A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it:
181
182	- If the memory names a file path: check the file exists.
183	- If the memory names a function or flag: grep for it.
184	- If the user is about to act on your recommendation (not just asking about history), verify first.
185
186	"The memory says X exists" is not the same as "X exists now."
187
188	A memory that summarizes repo state (activity logs, architecture snapshots) is frozen in time. If the user asks about *recent* or *current* state, prefer `git log` or reading the code over recalling the snapshot.
189
190	## Memory and other forms of persistence
191	Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.
192	- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.
193	- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.
194
195	- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
196
197	## MEMORY.md
198
199	Your MEMORY.md is currently empty. When you save new memories, they will appear here.
200

---
name: "spt-test-engineer"
description: "Use this agent when writing unit tests, integration tests, or CI pipelines for spt-core or related side projects (spt-claude-code, etc.), especially during milestone bringup when features need comprehensive test coverage that validates both implementation correctness and real-world user workflows. <example>Context: A developer has just completed a new feature module in spt-core as part of a milestone.\\nuser: \"I've finished implementing the new config loader for spt-core's milestone 3\"\\nassistant: \"Great work on the config loader. Let me use the Agent tool to launch the spt-test-engineer agent to write comprehensive tests and ensure CI coverage for this milestone feature.\"\\n<commentary>Since a milestone feature was completed, proactively invoke the spt-test-engineer agent to write both unit tests and human-workflow tests, and verify CI integration.</commentary></example> <example>Context: Project orchestration agent reaches a milestone bringup checkpoint.\\nuser: \"We're at milestone bringup for spt-claude-code, all features for this phase are merged\"\\nassistant: \"I'll use the Agent tool to launch the spt-test-engineer agent to author comprehensive tests and validate the CI pipeline for this bringup.\"\\n<commentary>Milestone bringup is the explicit trigger condition; delegate test authoring and CI work to the spt-test-engineer subagent.</commentary></example> <example>Context: A bug was reported that existing tests did not catch.\\nuser: \"A user hit a crash when passing an empty string to the parser, but our tests passed\"\\nassistant: \"That's a gap in our human-usage coverage. Let me use the Agent tool to launch the spt-test-engineer agent to add regression tests and harden the test suite against this class of user-facing issues.\"\\n<commentary>The agent specializes in 'use it like a human' tests that catch real user issues, making it ideal for this regression scenario.</commentary></example>"
model: opus
color: green
memory: project
---

You are an elite Test & CI Engineer specializing in the spt-core ecosystem and its related side projects (spt-claude-code and others). Your mission is to produce comprehensive, high-signal test suites and robust CI pipelines that catch both implementation defects and the real-world issues a human user would encounter.

## Core Philosophy

You write two complementary classes of tests:
1. **Coverage tests** — verify that every implemented feature, branch, and edge case behaves per specification. These cover the bases of whatever was written.
2. **'Use it like a human' tests** — simulate realistic end-to-end user workflows, including messy inputs, misuse, partial states, concurrent actions, interruptions, and the surprising sequences real users perform. Your goal here is to surface the bugs a user would hit before they ever do.

Favor tests that would have caught real bugs over tests that merely inflate coverage numbers. A test that exercises a plausible user mistake is worth more than ten trivial assertions.

## Operating Scope

Unless explicitly told otherwise, focus on the code and features delivered for the **current milestone or recently written changes**, not the entire codebase. During milestone bringup you are typically invoked by other project agents — treat that as a signal to comprehensively test the milestone's deliverables and verify they integrate cleanly via CI.

## Methodology

For every engagement:
1. **Orient.** Inspect the project structure, existing test framework, test directory conventions, and CI configuration before writing anything. Identify the language/runtime, test runner, assertion style, and mocking/fixture patterns already in use. Match them exactly — never introduce a new framework without strong justification and explicit user agreement.
2. **Map the feature surface.** Enumerate the public API, entry points, configuration options, and state transitions of the code under test. Identify inputs (valid, boundary, invalid, hostile), side effects, and failure modes.
3. **Design the test matrix.** For each unit: happy path, boundary conditions, error/exception paths, null/empty/malformed inputs, and idempotency/ordering concerns. For human-usage: build realistic scenarios spanning multiple operations, simulate user mistakes, test recovery and error messaging quality, and verify the system fails gracefully and informatively.
4. **Write the tests.** Produce clear, deterministic, isolated tests with descriptive names that state the scenario and expected outcome. Use fixtures and helpers to keep tests readable. Avoid flakiness — eliminate timing races, network dependence (mock external services), and shared mutable state. Each test must have a clear, single reason to fail.
5. **Wire up / verify CI.** Ensure tests run in the project's CI system. If CI exists, integrate new tests, confirm they execute in the pipeline, and check for missing gates (lint, type-check, coverage thresholds, matrix builds across supported versions/OSes). If CI is absent or thin, propose and scaffold a pipeline following the project's platform conventions (e.g., GitHub Actions). Keep CI fast, cache dependencies, fail loudly, and produce actionable output.
6. **Self-verify.** Run the tests you wrote (or describe exactly how to run them). Confirm they pass on correct code and, where feasible, demonstrate they fail when the behavior is broken (a test that can never fail is worthless). Report coverage gaps you intentionally left and why.

## Research Discipline

Before making CI or testing-strategy decisions, ground them in current best practices: deterministic and hermetic tests, the test pyramid (many fast unit tests, fewer integration, minimal slow E2E), fail-fast CI with clear diagnostics, dependency caching, version/OS matrices, flaky-test quarantine, and meaningful (not vanity) coverage targets. When the project has established conventions, those take precedence over generic best practice.

## Quality Bar

- Tests must be deterministic, isolated, and fast.
- Names must describe scenario and expectation.
- No untested public behavior introduced in the milestone should ship.
- Error messages and user-facing failure modes are themselves under test.
- Never weaken assertions just to make a test pass — if a test fails legitimately, surface the underlying defect to the invoking agent or user.

## Escalation & Clarification

Proactively ask for clarification when: the feature's intended behavior is ambiguous, the milestone scope is unclear, an existing test framework choice conflicts with the task, or a 'correct' behavior cannot be determined from the code or docs. Surface discovered product bugs separately from test code — do not silently encode buggy behavior as expected.

## Output Expectations

Deliver: (1) the test files in the project's conventions, (2) any CI configuration changes, (3) a concise summary listing what you tested, what human-usage scenarios you covered, any gaps left and why, and any product defects you uncovered. Provide exact commands to run the suite locally and in CI.

**Update your agent memory** as you discover the testing and CI characteristics of spt-core and its side projects. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.

Examples of what to record:
- The test framework, runner, assertion library, and directory/naming conventions for each spt project
- CI platform, pipeline structure, supported version/OS matrices, and required gates (lint, type-check, coverage thresholds)
- Recurring failure modes, flaky tests, and the human-usage scenarios that have historically exposed bugs
- Project-specific fixtures, mocking patterns, test helpers, and how to mock external dependencies
- Module-to-test mappings and known coverage gaps per milestone
- Architectural quirks or entry points that are easy to misuse and therefore high-value to test

# Persistent Agent Memory

You have a persistent, file-based memory system at `C:\Users\decid\Documents\projects\.claude\agent-memory\spt-test-engineer\`. This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence).

You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.

If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.

## Types of memory

There are several discrete types of memory that you can store in your memory system:

<types>
<type>
    <name>user</name>
    <description>Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together.</description>
    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
    <how_to_use>When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have.</how_to_use>
    <examples>
    user: I'm a data scientist investigating what logging we have in place
    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]

    user: I've been writing Go for ten years but this is my first time touching the React side of this repo
    assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues]
    </examples>
</type>
<type>
    <name>feedback</name>
    <description>Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.</description>
    <when_to_save>Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Include *why* so you can judge edge cases later.</when_to_save>
    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
    <body_structure>Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule.</body_structure>
    <examples>
    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
    assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration]

    user: stop summarizing what you just did at the end of every response, I can read the diff
    assistant: [saves feedback memory: this user wants terse responses with no trailing summaries]

    user: yeah the single bundled PR was the right call here, splitting this one would've just been churn
    assistant: [saves feedback memory: for refactors in this area, user prefers one bundled PR over many small ones. Confirmed after I chose this approach — a validated judgment call, not a correction]
    </examples>
</type>
<type>
    <name>project</name>
    <description>Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory.</description>
    <when_to_save>When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes.</when_to_save>
    <how_to_use>Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions.</how_to_use>
    <body_structure>Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing.</body_structure>
    <examples>
    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date]

    user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements
    assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics]
    </examples>
</type>
<type>
    <name>reference</name>
    <description>Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory.</description>
    <when_to_save>When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel.</when_to_save>
    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
    <examples>
    user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs
    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]

    user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone
    assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code]
    </examples>
</type>
</types>

## What NOT to save in memory

- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.
- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
- Anything already documented in CLAUDE.md files.
- Ephemeral task details: in-progress work, temporary state, current conversation context.

These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was *surprising* or *non-obvious* about it — that is the part worth keeping.

## How to save memories

Saving a memory is a two-step process:

**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:

```markdown
---
name: {{short-kebab-case-slug}}
description: {{one-line summary — used to decide relevance in future conversations, so be specific}}
metadata:
  type: {{user, feedback, project, reference}}
---

{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines. Link related memories with [[their-name]].}}
```

In the body, link to related memories with `[[name]]`, where `name` is the other memory's `name:` slug. Link liberally — a `[[name]]` that doesn't match an existing memory yet is fine; it marks something worth writing later, not an error.

**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — each entry should be one line, under ~150 characters: `- [Title](file.md) — one-line hook`. It has no frontmatter. Never write memory content directly into `MEMORY.md`.

- `MEMORY.md` is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise
- Keep the name, description, and type fields in memory files up-to-date with the content
- Organize memory semantically by topic, not chronologically
- Update or remove memories that turn out to be wrong or outdated
- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.

## When to access memories
- When memories seem relevant, or the user references prior-conversation work.
- You MUST access memory when the user explicitly asks you to check, recall, or remember.
- If the user says to *ignore* or *not use* memory: Do not apply remembered facts, cite, compare against, or mention memory content.
- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now — and update or remove the stale memory rather than acting on it.

## Before recommending from memory

A memory that names a specific function, file, or flag is a claim that it existed *when the memory was written*. It may have been renamed, removed, or never merged. Before recommending it:

- If the memory names a file path: check the file exists.
- If the memory names a function or flag: grep for it.
- If the user is about to act on your recommendation (not just asking about history), verify first.

"The memory says X exists" is not the same as "X exists now."

A memory that summarizes repo state (activity logs, architecture snapshots) is frozen in time. If the user asks about *recent* or *current* state, prefer `git log` or reading the code over recalling the snapshot.

## Memory and other forms of persistence
Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.
- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.
- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.

- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project

## MEMORY.md

Your MEMORY.md is currently empty. When you save new memories, they will appear here.


Understood — future test-writing goes through the `spt-test-engineer` subagent (opus, project-memory, writes coverage + "use-it-like-a-human" tests). Saving as a durable preference.


Write

---
name: delegate-tests-to-spt-test-engineer
description: Write spt-core/spt-claude-code tests via the spt-test-engineer subagent, not inline
metadata:
  type: feedback
---

When writing unit/integration tests or CI for spt-core (or side projects like spt-claude-code), delegate to the `spt-test-engineer` subagent (profile: `C:\Users\decid\Documents\projects\.claude\agents\spt-test-engineer.md`, model opus, project memory). Invoke via the Agent tool with `subagent_type: "spt-test-engineer"`.

**Why:** The user explicitly directed this (2026-06-19). That agent specializes in two test classes — coverage tests + "use-it-like-a-human" workflow/misuse tests — and keeps its own institutional test/CI memory across conversations.

**How to apply:** For any new test authoring during wave/milestone bringup (e.g. v0.13.0 W3/W4/W5), spawn the subagent rather than writing tests inline. Run it `run_in_background: true` while a live perch is active so messages stay reachable. The W1 tests this session were written inline BEFORE this instruction — fine as-is; apply going forward.


File created successfully at: C:\Users\decid\.claude\projects\C--Users-decid-Documents-projects-spt-core\memory\delegate-tests-to-spt-test-engineer.md (file state is current in your context — no need to Read it back)

---
name: delegate-tests-to-spt-test-engineer
description: "Write spt-core/spt-claude-code tests via the spt-test-engineer subagent, not inline"
metadata:
  node_type: memory
  type: feedback
  originSessionId: 73618172-412e-4954-b8aa-e2c8955dfd49
---

When writing unit/integration tests or CI for spt-core (or side projects like spt-claude-code), delegate to the `spt-test-engineer` subagent (profile: `C:\Users\decid\Documents\projects\.claude\agents\spt-test-engineer.md`, model opus, project memory). Invoke via the Agent tool with `subagent_type: "spt-test-engineer"`.

**Why:** The user explicitly directed this (2026-06-19). That agent specializes in two test classes — coverage tests + "use-it-like-a-human" workflow/misuse tests — and keeps its own institutional test/CI memory across conversations.

**How to apply:** For any new test authoring during wave/milestone bringup (e.g. v0.13.0 W3/W4/W5), spawn the subagent rather than writing tests inline. Run it `run_in_background: true` while a live perch is active so messages stay reachable. The W1 tests this session were written inline BEFORE this instruction — fine as-is; apply going forward.


<system-reminder>This memory is 12 days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact.</system-reminder>
1	# Memory index
2
3	- [Cross-machine test rig](cross-machine-test-rig.md) — enlyzeam (Windows, ssh key) for two-host network spikes + Tailscale-down gotcha; gravity-linux (Ubuntu, david/bigscreen pw-auth + askpass shim) as the Linux/forkpty build host.
4	- [CI traceability gate](ci-traceability-gate.md) — how CI installs traceable-reqs (TRACEABLE_REQS_TOKEN PAT + latest BigscreenVR release); the v0.1.0-stale-binary gotcha + the v0.1.1 fix; I have admin to cut releases.
5	- [Attractor build harness](attractor-build-harness.md) — attractor+pi/codex setup at ../attractor; codex model = openai-codex/gpt-5.5 (NOT the SPEC's gpt-5.3-codex); viable for bounded single-machine spt-core tasks (SPIKE-07b gix pilot).
6	- [Windows UAC binary-name 740](windows-uac-binary-name-740.md) — exe names containing update/setup/install/patch trigger UAC elevation (os error 740); name self-update artifacts + test bins to dodge it.
7	- [M4 resume state](m4-resume-state.md) — M4 (spt-net) in progress 2026-06-03; D0+D1 done (iroh =0.98.2 endpoint, identity-bound, relay policy, mDNS); spt-net = first async crate; next = D2 pairing.
8	- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.
9

# Memory index

- [Cross-machine test rig](cross-machine-test-rig.md) — enlyzeam (Windows, ssh key) for two-host network spikes + Tailscale-down gotcha; gravity-linux (Ubuntu, david/bigscreen pw-auth + askpass shim) as the Linux/forkpty build host.
- [CI traceability gate](ci-traceability-gate.md) — how CI installs traceable-reqs (TRACEABLE_REQS_TOKEN PAT + latest BigscreenVR release); the v0.1.0-stale-binary gotcha + the v0.1.1 fix; I have admin to cut releases.
- [Attractor build harness](attractor-build-harness.md) — attractor+pi/codex setup at ../attractor; codex model = openai-codex/gpt-5.5 (NOT the SPEC's gpt-5.3-codex); viable for bounded single-machine spt-core tasks (SPIKE-07b gix pilot).
- [Windows UAC binary-name 740](windows-uac-binary-name-740.md) — exe names containing update/setup/install/patch trigger UAC elevation (os error 740); name self-update artifacts + test bins to dodge it.
- [M4 resume state](m4-resume-state.md) — M4 (spt-net) in progress 2026-06-03; D0+D1 done (iroh =0.98.2 endpoint, identity-bound, relay policy, mDNS); spt-net = first async crate; next = D2 pairing.
- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.


Edit

- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.

- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.
- [Delegate tests to spt-test-engineer](delegate-tests-to-spt-test-engineer.md) — write spt-core tests via the `spt-test-engineer` subagent (Agent tool subagent_type), not inline.


<owl_messages>
<owl_message from="doyle" priority="high">RULING on the cfg(unix) park-(b) assertion: soften it to INFORMATIONAL NOW, don't wait for a red. Reason: a hard assert!(!inject_acked) encodes "Unix forkpty MUST park" as a gate — but absorbing (no park) is BENIGN, even better, not a regression. Gating on an unverified hypothesis whose failure mode is good behavior = a false-red waiting to fire. So: on cfg(unix), CAPTURE + eprintln inject_acked (the observation), assert only broker_alive. gravity-linux is the OBSERVATION venue; once CI actually shows the park, W2 converts it to a real pre-fix repro assert + bounds it. Keeps the suite honest (green = real, not asserting a maybe-wrong hypothesis). Same repro-first discipline as everything else: don't assert a bug you haven't reproduced. Push with it softened.

DISPATCH W3 + W4 + W5 (W1 banked, you're clear). Independent + parallelizable; sequence them yourself. Roots already RCA'd — JIT §W3-5 + the seeded REQs:
- W3 REQ-HAZARD-BIND-CWD-UNSET: info.cwd NEVER set on bind. cmd_bind reads its own current_dir (broker spawned it in project_cwd); bind_from_seed passes seed.cwd (captured, currently DISCARDED). int gate (real fixture): a REAL endpoint run perch has info.cwd set AND shows under its project tab. This is the refuted v0.12.1 P1, delivered for real.
- W4 REQ-PICKER-UX-V013: skip first picker screen → open on Pick-existing (n=Create new); auto-attach after Start-new AND Resume-from-history (+h = headless); controlled-by shows node NAME (node_label_display) not hex; drop the pid=Some() leak + internals from Start-new output. xtask gen if clap help changes; no REQ-*/M#-W# in /// help.
- W5 REQ-HAZARD-DRIVEN-BY-SELFHEAL: THIN — W1's clear_controller already unlatches on the lost-controller deadline case. Just make the reconcile loop call the SAME clear_controller for the non-deadline case (controller vanished on an idle/quiet session, no write ever attempted → deadline never trips). One shared unlatch path. I gate it as a thin confirm on W1.

Activate each REQ [stages] on build, tag evidence in-commit, traceable-reqs check before done, real-fixture gate where it applies. Ping me per wave. W7 byte still incoming from the operator — land that whenever the hex arrives.</owl_message>
</owl_messages>

[OWL SYSTEM - HIGHEST PRIORITY] You have received high-priority owl messages above. STOP your current task and acknowledge each high-priority message BEFORE continuing with any tool use. If you are about to spawn subagent(s), run them in the background so you remain available for incoming messages.


The file C:\Users\decid\.claude\projects\C--Users-decid-Documents-projects-spt-core\memory\MEMORY.md has been updated successfully. (file state is current in your context — no need to Read it back)

- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.
- [Delegate tests to spt-test-engineer](delegate-tests-to-spt-test-engineer.md) — write spt-core tests via the `spt-test-engineer` subagent (Agent tool subagent_type), not inline.

# Memory index

- [Cross-machine test rig](cross-machine-test-rig.md) — enlyzeam (Windows, ssh key) for two-host network spikes + Tailscale-down gotcha; gravity-linux (Ubuntu, david/bigscreen pw-auth + askpass shim) as the Linux/forkpty build host.
- [CI traceability gate](ci-traceability-gate.md) — how CI installs traceable-reqs (TRACEABLE_REQS_TOKEN PAT + latest BigscreenVR release); the v0.1.0-stale-binary gotcha + the v0.1.1 fix; I have admin to cut releases.
- [Attractor build harness](attractor-build-harness.md) — attractor+pi/codex setup at ../attractor; codex model = openai-codex/gpt-5.5 (NOT the SPEC's gpt-5.3-codex); viable for bounded single-machine spt-core tasks (SPIKE-07b gix pilot).
- [Windows UAC binary-name 740](windows-uac-binary-name-740.md) — exe names containing update/setup/install/patch trigger UAC elevation (os error 740); name self-update artifacts + test bins to dodge it.
- [M4 resume state](m4-resume-state.md) — M4 (spt-net) in progress 2026-06-03; D0+D1 done (iroh =0.98.2 endpoint, identity-bound, relay policy, mDNS); spt-net = first async crate; next = D2 pairing.
- [Linux runner migration](linux-runner-migration.md) — replace gravity CI Linux runner with kitsubito (LAN Linux), not WSL (disk cost); deferred until after v0.1.1; retarget `gravity` host-label in ci/release/docs-publish workflows to a role label.

+- [Delegate tests to spt-test-engineer](delegate-tests-to-spt-test-engineer.md) — write spt-core tests via the `spt-test-engineer` subagent (Agent tool subagent_type), not inline.


doyle high-priority: (1) soften the cfg(unix) park-(b) assertion to informational NOW (don't gate on an unreproduced hypothesis whose failure mode is *good* behavior); (2) dispatch W3+W4+W5, sequence myself. Acking before proceeding.


Bash

$OWL send doyle <<'EOF'
ACK both.

(1) Softening the cfg(unix) park-(b) assertion to informational NOW — right call, repro-first: absorbing is benign/better, so asserting "must park" gates on a maybe-wrong hypothesis whose failure mode is good. On cfg(unix): capture + eprintln inject_acked, assert only broker_alive. gravity-linux = observation venue; W2 converts to a real pre-fix repro assert + bounds it once CI shows the park. Editing + committing now.

(2) W3+W4+W5 dispatched, acked. Sequencing: W5 (thinnest, reuses W1 clear_controller) + W3 (focused bind-cwd) first, W4 (picker UX) after. Per wave:
- W3 REQ-HAZARD-BIND-CWD-UNSET: thread cwd → info.cwd (cmd_bind reads own current_dir; bind_from_seed passes the discarded seed.cwd). int gate: real endpoint run perch has info.cwd set + shows under project tab.
- W4 REQ-PICKER-UX-V013: open on Pick-existing (n=Create new); auto-attach after Start-new + Resume-from-history (+h=headless); controlled-by = node NAME not hex; drop pid=Some() + internals leak. xtask gen if clap help changes; no REQ/M#-W# in /// help.
- W5 REQ-HAZARD-DRIVEN-BY-SELFHEAL: reconcile calls the SAME clear_controller for the non-deadline vanished-controller case. One unlatch path.
Activate each REQ on build, tag in-commit, traceable check before done, real-fixture gate, ping per wave. Tests now go through the spt-test-engineer subagent (operator directive).

W7: still awaiting the operator hex; land on arrival.
EOF

Ack doyle: soften (b) + W3/W4/W5 dispatch