- 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: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
- 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".
- 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 remote agents (routines) that execute on a cron schedule. - When the user wants to schedule a recurring remote 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: Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements).
TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project.
SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML.
- 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 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.


Secret set. Commit + push `ci.yml`, then watch the traceability job.


Bash

git add .github/workflows/ci.yml && git commit -q -m "ci: install traceable-reqs with a PAT secret (cross-org private repo)

The default repo-scoped GITHUB_TOKEN cannot read the private cross-org
BigscreenVR/traceable-reqs, so the traceability job's binary download
failed with 'release not found'. Use a TRACEABLE_REQS_TOKEN repo secret
(a PAT with read access to that repo) instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>" && git push origin dev-freeform 2>&1 | tail -3

Commit + push ci.yml


warning: in the working copy of '.github/workflows/ci.yml', LF will be replaced by CRLF the next time Git touches it
To https://github.com/SaberMage/spt-core.git
   a32b071..5c26a4b  dev-freeform -> dev-freeform


sleep 5; RID=$(gh run list --branch dev-freeform --limit 1 --json databaseId --jq '.[0].databaseId' 2>&1); echo "run=$RID"; gh run watch "$RID" --exit-status --interval 20 2>&1 | tail -20; echo "WATCH_EXIT=$?"

Watch the new CI run


run=26814794557
  ✓ Post Cache cargo
  ✓ Post Run actions/checkout@v4
  ✓ Complete job

ANNOTATIONS
! Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4. Actions will be forced to run with Node.js 24 by default starting June 16th, 2026. Node.js 20 will be removed from the runner on September 16th, 2026. Please check if updated versions of these actions are available that support Node.js 24. To opt into Node.js 24 now, set the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true environment variable on the runner or in your workflow file. Once Node.js 24 becomes the default, you can temporarily opt out by setting ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true. For more information see: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
traceability: .github#2

X Process completed with exit code 1.
traceability: .github#4541

! Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4. Actions will be forced to run with Node.js 24 by default starting June 16th, 2026. Node.js 20 will be removed from the runner on September 16th, 2026. Please check if updated versions of these actions are available that support Node.js 24. To opt into Node.js 24 now, set the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true environment variable on the runner or in your workflow file. Once Node.js 24 becomes the default, you can temporarily opt out by setting ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true. For more information see: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
test (ubuntu-latest): .github#4

! Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4. Actions will be forced to run with Node.js 24 by default starting June 16th, 2026. Node.js 20 will be removed from the runner on September 16th, 2026. Please check if updated versions of these actions are available that support Node.js 24. To opt into Node.js 24 now, set the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true environment variable on the runner or in your workflow file. Once Node.js 24 becomes the default, you can temporarily opt out by setting ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true. For more information see: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
test (windows-latest): .github#3

- NOTICE: windows-latest requests are being redirected to windows-2025-vs2026 by June 15, 2026
test (windows-latest): .github#1

WATCH_EXIT=0


Still red — get the failing step detail (install vs coverage gate).


gh run view 26814794557 --log-failed 2>&1 | grep -iE "traceable|release|not found|denied|403|401|token|error|MISSING|FAIL|uncovered" | head -20

Traceability failure detail


traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1574366Z ##[group]Run ./traceable-reqs check --json
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1575089Z ./traceable-reqs check --json
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1604892Z shell: /usr/bin/bash -e {0}
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1605235Z ##[endgroup]
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1709476Z {
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1709873Z   "schemaVersion": 1,
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1710177Z   "summary": {
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1710499Z     "requirementCount": 116,
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1710844Z     "completeCount": 116,
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1711150Z     "incompleteCount": 0,
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1711440Z     "findingCount": 7
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1711990Z   },
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1712487Z   "requirements": [
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1713006Z     {
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1713492Z       "id": "REQ-API-1",
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1714377Z       "title": "api prefix and adapter_name on every machinery invocation",
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1715083Z       "requiredStages": [
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1715553Z         "impl",
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1715982Z         "unit",
traceability	Coverage gate (hard — fails PR on uncovered activated req)	2026-06-02T10:47:23.1716366Z         "int"


Big progress — the **PAT worked**: install succeeded, and the coverage gate ran. JSON shows **116/116 complete, 0 incomplete, but findingCount 7** and exit 1. Locally `check` (non-JSON) exits 0; CI runs `check --json`. Need to see the 7 findings + why `--json` exits 1 — and check version skew (CI uses v0.1.0 release; my local binary may differ).


echo "=== local binary version ==="; /c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs --version 2>&1 | head -1; echo "=== local check --json exit ==="; /c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs check --json >/tmp/lj.json 2>&1; echo "local --json exit=$?"; grep -E "findingCount|completeCount|requirementCount|incompleteCount" /tmp/lj.json | head

Local binary version + check --json exit/findings


=== local binary version ===
traceable-reqs 0.1.0
=== local check --json exit ===
local --json exit=0
    "requirementCount": 116,
    "completeCount": 116,
    "incompleteCount": 0,
    "findingCount": 0


Same binary version (0.1.0), and locally `check --json` gives **0 findings, exit 0** — but CI gives **7 findings, exit 1** on the same committed code. Need to see what the 7 findings actually are.


gh run view 26814794557 --log-failed 2>&1 | grep -iE '"kind"|"severity"|"message"|"detail"|"file"|"tag"|finding' | grep -iv "fails PR on uncovered" | head -40

Extract the 7 findings from CI log


(Bash completed with no output)


gh run view 26814794557 --log-failed 2>&1 | grep "Coverage gate" | sed 's/^.*check --json[^ ]*Z//; s/^.*[0-9]Z[[:space:]]*//' | grep -iE "finding|severity|message|orphan|stale|untagged|duplicate|warn|error|\"id\"" | head -40

Filter findings text from coverage step


"findingCount": 7
"id": "REQ-API-1",
"id": "REQ-API-2",
"id": "REQ-API-3",
"id": "REQ-ARCH-1",
"id": "REQ-ARCH-2",
"id": "REQ-ARCH-3",
"id": "REQ-ARCH-4",
"id": "REQ-DAEMON-1",
"id": "REQ-DAEMON-2",
"id": "REQ-DAEMON-3",
"id": "REQ-DAEMON-4",
"id": "REQ-DOCS-1",
"id": "REQ-DOCS-2",
"id": "REQ-DOCS-3",
"id": "REQ-DOCS-4",
"id": "REQ-DOCS-5",
"id": "REQ-EP-1",
"id": "REQ-EP-2",
"id": "REQ-EP-3",
"id": "REQ-EP-4",
"id": "REQ-FRONT-1",
"id": "REQ-HAZARD-CASCADE-WIPE-GUARD",
"id": "REQ-HAZARD-CONPTY-DSR",
"id": "REQ-HAZARD-DAEMON-HOSTED-LIVENESS",
"id": "REQ-HAZARD-DEFERRED-DRAIN",
"id": "REQ-HAZARD-DEFERRED-SURVIVE-DRAIN",
"id": "REQ-HAZARD-DIRECT-WRITE-PRECEDENCE",
"title": "Direct-write precedence marker (with node id) guards stale overwrite (6.5)",
"id": "REQ-HAZARD-DROP-FILE-SINGLE-WRITER",
"id": "REQ-HAZARD-EBUSY-RENAME",
"id": "REQ-HAZARD-ECHO-BEFORE-SIGNOFF",
"title": "Echo-commune fires before INIT_SIGNOFF on orphan teardown (3.3)",
"id": "REQ-HAZARD-ENVELOPE-DECODE-ORDER",
"id": "REQ-HAZARD-ENVELOPE-PARSER-SAFE",
"id": "REQ-HAZARD-EPHEMERAL-CLEANUP",
"id": "REQ-HAZARD-EVENTPART-REASSEMBLY",
"title": "EVENT-PART split/reassembly is byte-exact; orphan parts dropped silently",
"id": "REQ-HAZARD-GEN-START-NOW",
"id": "REQ-HAZARD-GRACE-BEFORE-SIGNOFF",


Same binary, so the difference is working-tree content: locally I have an **uncommitted M3b-PLAN.md rewrite**; CI has the committed stub. So the committed tree generates 7 findings mine doesn't. Reproduce CI exactly by stashing.


git status --short; echo "=== stash + recheck (reproduces CI committed tree) ==="; git stash push -u -m m3b-plan-wip >/dev/null 2>&1; /c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs check --json >/tmp/ci-repro.json 2>&1; echo "exit=$?"; grep -E "findingCount" /tmp/ci-repro.json

Stash WIP, reproduce CI findings


 M M3b-PLAN.md
=== stash + recheck (reproduces CI committed tree) ===
exit=0
    "findingCount": 0


1	# M3b Plan — `spt-daemon` broker/brain process (stub)
2
3	> **Just-in-time, lightweight** — same pattern as `M0/M1/M2a/M2b/M3a-PLAN.md`. The
4	> ordered task layer between `ROADMAP.md`, `M3-PLAN.md` (the M3 umbrella), and
5	> `traceable-reqs.toml`, scoped to **M3b only**. Branch: `dev-freeform`. This is a
6	> **stub** — the full task table is authored when M3b starts (after M3a, now
7	> delivered). Authoritative scope lives in [`M3-PLAN.md`](./M3-PLAN.md) §M3b.
8
9	> **Upstream is done:** Phase 0 spike-gate ✅ (Spikes #3/#4/#5/#6 PASS) and **M3a
10	> ✅ delivered** — `spt-term` provides the single-surface PTY *mechanism*
11	> (SessionSurface + ConPTY/forkpty backend + DSR drain + injection + bounded
12	> byte-stream + digest parser primitive). **M3b builds the *process* that hosts
13	> many of those surfaces** behind versioned IPC.
14
15	## Goal
16
17	Replace the interim no-daemon model (M1/M2a/M2b: the `api listen` process holds
18	the perch + relays, seed bridges via a file) with the **real architecture**
19	(ADR-0004): one per-machine `spt-daemon` with a **broker/brain split** that owns
20	all per-machine state and re-hosts the M2b lifecycle as in-process loops with
21	**daemon-authoritative liveness**, hosting `spt-term` surfaces behind a versioned
22	local IPC, with an **idempotent** broker↔brain boundary and **auto-start**.
23
24	**M3b done =** the daemon hosts the LiveAgent lifecycle (Psyche-as-loop, no
25	interim glue); the broker hosts `spt-term` PTYs behind versioned IPC; liveness is
26	the daemon's `status` field (not `is_process_alive(pid)`); every broker↔brain
27	side-effect boundary is idempotent (Spike #6); any `api` call auto-starts the
28	daemon; `cargo test --workspace` + clippy `-D warnings` + `traceable-reqs check`
29	green on the CI matrix.
30
31	## Scope (authoritative detail: `M3-PLAN.md` §M3b)
32
33	### In — the `spt-daemon` crate (above `spt-live`, below `spt`)
34
35	- **broker** (stable kernel) — owns only un-transferable resources per the
36	  ADR-0004 §B table: PTY master handles (**from `spt-term`**), spawned harness
37	  children, accepted local client sockets, listening sockets. Minimal **versioned
38	  local IPC** (`REQ-HAZARD-HANDOFF-ARGV-COMPAT` / 2.3).
39	- **brain** (userspace) — routing, registry, the re-hosted M2b lifecycle
40	  (Psyche-as-loop + durable pulse period), manifest parse. Restarts freely;
41	  rehydrates from disk + re-attaches to broker-held handles. `gen_start = now()`
42	  on cold-start **and** handoff (`REQ-HAZARD-GEN-START-NOW` / 2.4).
43	- **consolidation** (`REQ-DAEMON-1`) — poll-listener + Psyche/pulse loops move
44	  into the daemon; only the thin stateless in-session relay remains (topology 1).
45	- **daemon-authoritative liveness** (`REQ-HAZARD-DAEMON-HOSTED-LIVENESS` / 2.5).
46	- **idempotent delivery** (`REQ-HAZARD-RESTART-IDEMPOTENT` / 7.2 — Spike #6).
47	- **auto-start** (`REQ-DAEMON-3`) + **spt-hosted startup** (`REQ-START-3`: spawn →
48	  `api bind`, in-memory seed, no seed file) + **orphan-watch** (carry the M2b
49	  grace 1.1 / echo 3.3 / stale-sweep 3.2 ordering into the supervised-crash path).
50	- **digest daemon-half** — the M3b completion of REQ-TERM-4: manifest-sourcing of
51	  the `input/agent/tool` patterns, `spt digest <[subnet:]id[@node]>` snapshot
52	  pull, the broker-pushed structured **delta-stream** (riding the R-TERM-3
53	  byte-stream substrate), and opt-in Path-B persistence. **Activates REQ-TERM-4
54	  `int`** over the M3a parser primitive.
55
56	### Out
57
58	- networking / P2P + multi-subnet + notifications (M4); the QUIC-stream broker
59	  ownership *implementation* (M4 — shape validated by Spike #3); self-update (M3c).
60
61	## Requirements to activate (currently `required_stages = []`)
62
63	`REQ-DAEMON-1/3`, `REQ-START-3`, `REQ-HAZARD-DAEMON-HOSTED-LIVENESS`,
64	`REQ-HAZARD-RESTART-IDEMPOTENT`, `REQ-HAZARD-HANDOFF-ARGV-COMPAT`,
65	`REQ-HAZARD-GEN-START-NOW`, and **REQ-TERM-4 `int`** (the digest daemon-half).
66	Activate each as its task lands (TRACEABILITY rule 5). New requirements →
67	register in `traceable-reqs.toml` first (rule 3).
68
69	## Workspace change
70
71	Add `crates/spt-daemon` (sixth-ish layer, above `spt-live`, below `spt`):
72
73	```
74	spt-proto → spt-store → spt-msg → {spt-net, spt-term, spt-runtime} → spt-live → spt-daemon → spt
75	```
76
77	## Carried constraints
78
79	- **Versioned IPC = newer brain ↔ older broker** (`REQ-HAZARD-HANDOFF-ARGV-COMPAT`):
80	  the broker is the stable kernel; never break its handoff contract.
81	- **`spt-term` is single-surface per handle** — the daemon supplies the
82	  multiplexed, name-addressable, attach/detach supervisor *around* it. Do not push
83	  fleet/registry concerns back down into `spt-term`.
84	- **OS stream-neutrality (Spike #4/#5)** continues to hold through the IPC: the
85	  delta-stream is a structured overlay on the same OS-neutral byte stream.


Restore my WIP, then the committed tree is local-clean (0) but CI-dirty (7) with the same binary version — so it's platform/line-ending, not content. Get the actual findings from CI.


git stash pop >/dev/null 2>&1; echo "restored"; echo "=== CI findings array ==="; gh run view 26814794557 --log-failed 2>&1 | grep "Coverage gate" | sed -E 's/^[^Z]*Z[[:space:]]*//' > /tmp/cilog.txt; python3 -c "
import re,json
txt=open('/tmp/cilog.txt').read()
i=txt.find('{')
# find the JSON object spanning braces
depth=0;start=None
for k,ch in enumerate(txt[i:],i):
    if ch=='{':
        if depth==0:start=k
        depth+=1
    elif ch=='}':
        depth-=1
        if depth==0:
            obj=txt[start:k+1]
            try:
                d=json.loads(obj)
                print('findings:',json.dumps(d.get('findings',[]),indent=1)[:1500])
                break
            except Exception as e:
                pass
" 2>&1 | head -50

Restore WIP + extract findings JSON from CI log


restored
=== CI findings array ===
Traceback (most recent call last):
  File "<string>", line 3, in <module>
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/cilog.txt'


gh run view 26814794557 --log-failed > /tmp/failed.log 2>&1; wc -l /tmp/failed.log; python3 - <<'PY'
import re,json
lines=open('/tmp/failed.log',encoding='utf-8',errors='replace').read().splitlines()
# keep only Coverage gate step lines, strip the "job\tstep\tTIMESTAMP " prefix
buf=[]
for ln in lines:
    if 'Coverage gate' in ln:
        # strip up to and including the ISO timestamp
        m=re.search(r'\dZ\s?(.*)$', ln)
        buf.append(m.group(1) if m else '')
txt='\n'.join(buf)
i=txt.find('{')
depth=0;start=None
for k in range(i,len(txt)):
    ch=txt[k]
    if ch=='{':
        if depth==0:start=k
        depth+=1
    elif ch=='}':
        depth-=1
        if depth==0:
            try:
                d=json.loads(txt[start:k+1])
                print('summary:',d['summary'])
                print('FINDINGS:')
                print(json.dumps(d.get('findings',[]),indent=1))
            except Exception as e:
                print('parse fail',e)
            break
PY

Parse findings JSON from failed log


Error: Exit code 1
4541 /tmp/failed.log
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/failed.log'


Path mismatch (git-bash `/tmp` vs Windows-python). Grep the findings array directly from the log.


gh run view 26814794557 --log-failed 2>&1 | grep "Coverage gate" | sed -E 's/^[^Z]*Z[[:space:]]?//' | awk '/"findings"/{f=1} f' | head -60

Show findings array lines from CI


  "findings": [
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 12,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 24,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 25,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 29,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 33,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 37,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    },
    {
      "code": "parse_error",
      "severity": "must",
      "path": "docs/TRACEABILITY.md",
      "line": 45,
      "message": "Tag-shaped token does not match [stage->REQ-ID]"
    }
  ]
}
##[error]Process completed with exit code 1.


The 7 findings: `docs/TRACEABILITY.md` has **tag-shaped example tokens** (lines 12/24/25/29/33/37/45) the parser flags as malformed real tags — severity `must` → exit 1. It passes locally only because Windows **CRLF** masks the match; on CI's LF they trip. Same line-ending-masked class as before. Read the offending lines.


Show the tag-shaped doc tokens (with line-ends)


1. **The manifest is the authoritative requirement registry.** Every PRD `R-*` requirement and every KNOWN-HAZARDS invariant exists in `traceable-reqs.toml` as a `REQ-*` id. No work without a REQ; no REQ without intent to satisfy. The PRD holds the prose; the manifest holds the id + `required_stages`.
2. **Tag in the same change as the evidence.** When you write the function / test / doc-section that satisfies a stage, add its `[<stage>-><REQ-ID>]` tag in *that same commit*. Never "tag later" M-bM-^@M-^T this single rule is what stops the trace from drifting.
3. **Evidence-proximate tags, not file-tops.** A tag sits on or immediately above the real function, test, doc section, config entry, or workflow step that proves the stage. One tag = one piece of real evidence. Tags at file tops to satisfy coverage are noise and usually wrong.
4. **KNOWN-HAZARDS are first-class requirements.** Each invariant is a `REQ-HAZARD-*` requiring `unit` (and `int` where cross-process/cross-node). A hazard cannot be "covered" without a test tagging it M-bM-^@M-^T the anti-regression promise becomes mechanical (PRD success criterion #6).

Real tags are `[<stage>->REQ-ID]` with a bare stage word. The examples below
angle-bracket the stage (`[<impl>->...]`) only so the scanner treats them as
illustrations, not live evidence M-bM-^@M-^T write a bare stage word in real code.

```rust
// [<impl>->REQ-PAIR-1]
fn spake2_pair(...) { ... }
```rust
// [<unit>->REQ-HAZARD-ENVELOPE-DECODE-ORDER]
#[test] fn decodes_amp_last() { ... }
```
```markdown
<!-- [<doc>->REQ-NET-2] -->
## Relay dependency
2. **Milestone activation gate.** Starting a milestone flips its reqs from `[]` to the real policy; the milestone **is not done until `check` is green for its reqs**. Coverage grows *with* the project instead of failing on day one.
3. **Agent-facing rule.** The repo `CLAUDE.md` instructs every dev-agent: tag `[<stage>-><REQ-ID>]` in the same change as the evidence, and run `traceable-reqs check` before declaring done. Since spt-core is built *with* agents, the contract must be machine-followable M-bM-^@M-^T agent discipline + CI as the net.
4. **Quality audit (anti-box-ticking).** `check` proves a tag *exists*; `traceable-reqs review` + `lint` audit whether tags sit near *real* evidence and whether titles are meaningful. Run advisory in CI (or periodically). Presence = hard gate; quality = audited.


The 7 are all in `docs/TRACEABILITY.md` — example tokens like `[<impl>->REQ-PAIR-1]`. The doc *intends* the angle-brackets to make them illustrations, but **released v0.1.0 doesn't honor that escape** — it flags them `must`. My local binary says 0.1.0 too but passes, so it's likely a newer-than-released build. Let me confirm by running the actual released v0.1.0 binary locally + check for an ignore mechanism.


cd /tmp 2>/dev/null; gh release download v0.1.0 --repo BigscreenVR/traceable-reqs --pattern '*windows-x86_64.exe' -O tr-released.exe --clobber 2>&1 | tail -2; echo "=== released v0.1.0 on committed tree ==="; git stash push -u >/dev/null 2>&1; /tmp/tr-released.exe check --json 2>&1 | grep -E "findingCount|TRACEABILITY|parse_error" | head; echo "released-exit via check (human):"; /tmp/tr-released.exe check >/dev/null 2>&1; echo $?; git stash pop >/dev/null 2>&1; echo "=== ignore mechanism? ==="; /c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs check --help 2>&1 | grep -iE "ignore|exclude|skip|config" | head

Run released v0.1.0 locally + look for ignore option


=== released v0.1.0 on committed tree ===
released-exit via check (human):
2
=== ignore mechanism? ===
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


Confirmed: released **v0.1.0 flags** those example tokens (exit 2 locally too); my local binary is a newer build that honors the angle-bracket escape. So CI uses a binary **older than the doc convention** `docs/TRACEABILITY.md` was written for. Let me check if v0.1.0 has an ignore/exclude before laying out options.


/c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs check --help 2>&1 | head -40

traceable-reqs check help (ignore/exclude options)


Usage: traceable-reqs.exe check [OPTIONS]

Options:
      --json
      --type <TYPE>
      --fail-on <LEVEL>  Lowest priority that fails check. Findings below this level still print but do not change the exit code. Default: must [default: must]
  -h, --help             Print help


Found it. Summary of the situation:

- **Test matrix: green.** Coverage: **116/116 complete.** The only failures are **7 `parse_error` findings (severity `must`)** in `docs/TRACEABILITY.md` — its example tokens `[<impl>->REQ-PAIR-1]` etc. The doc *intends* the angle-brackets to mark them as illustrations; **released v0.1.0 doesn't honor that escape and flags them**. Your local binary (a newer "0.1.0" build) does honor it — that's why it's masked locally.
- `check` has `--fail-on <LEVEL>` (default `must`) but no file-exclude; these are `must`, so that won't cleanly skip them.

Root cause: **CI's pinned v0.1.0 is older than the tag convention `TRACEABILITY.md` was written for.** Three ways to green:


AskUserQuestion

Question: How to green the traceability job? (test matrix already passes; coverage is 116/116 — only 7 doc-example parse_errors remain)

Choices:
Edit docs/TRACEABILITY.md's 7 example tokens so released v0.1.0 doesn't read them as tags (e.g. unicode arrow / different bracketing) + note the real format. Self-contained, deterministic, ~5 min. Downside: slightly uglier examples; redundant once CI uses a newer binary.
Cut a new BigscreenVR/traceable-reqs release (the build that honors [<stage>->...]) and CI downloads it. Root-cause fix, doc stays as-is. Touches your other repo; you'd cut the release.
Change ci.yml to `cargo install --git` the newer traceable-reqs rev (now possible with the PAT) instead of the v0.1.0 release. Root-cause fix, no new release. Adds CI build time + needs the newer rev to be the fix.
Accept the traceability job red for now (test matrix is green; coverage is actually 116/116). Revisit when you next touch traceable-reqs.


Your questions have been answered: "How to green the traceability job? (test matrix already passes; coverage is 116/116 — only 7 doc-example parse_errors remain)"="Ship newer traceable-reqs". You can now continue with these answers in mind.

Question: How to green the traceability job? (test matrix already passes; coverage is 116/116 — only 7 doc-example parse_errors remain)

Choices:
Edit docs/TRACEABILITY.md's 7 example tokens so released v0.1.0 doesn't read them as tags (e.g. unicode arrow / different bracketing) + note the real format. Self-contained, deterministic, ~5 min. Downside: slightly uglier examples; redundant once CI uses a newer binary.
Cut a new BigscreenVR/traceable-reqs release (the build that honors [<stage>->...]) and CI downloads it. Root-cause fix, doc stays as-is. Touches your other repo; you'd cut the release.
Change ci.yml to `cargo install --git` the newer traceable-reqs rev (now possible with the PAT) instead of the v0.1.0 release. Root-cause fix, no new release. Adds CI build time + needs the newer rev to be the fix.
Accept the traceability job red for now (test matrix is green; coverage is actually 116/116). Revisit when you next touch traceable-reqs.


"Ship newer" it is. First, do I even have write access to cut a release on `BigscreenVR/traceable-reqs`, and does the repo HEAD actually contain the escape-honoring fix? Checking both.


Bash

echo "=== my permission on BigscreenVR/traceable-reqs ==="; gh api repos/BigscreenVR/traceable-reqs --jq '.permissions' 2>&1 | head; echo "=== latest release vs HEAD date ==="; gh api repos/BigscreenVR/traceable-reqs/commits/HEAD --jq '.commit.committer.date + "  " + .sha[0:8] + "  " + (.commit.message|split("\n")[0])' 2>&1 | head; echo "release v0.1.0 published: 2026-05-04"; echo "=== local binary path/source hint ==="; /c/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs --help 2>&1 | head -3

Check write perms + HEAD recency


=== my permission on BigscreenVR/traceable-reqs ===
{"admin":true,"maintain":true,"pull":true,"push":true,"triage":true}
=== latest release vs HEAD date ===
2026-05-15T19:23:06Z  936f00b4  Quote SKILL.md description to fix YAML frontmatter (#7) (#11)
release v0.1.0 published: 2026-05-04
=== local binary path/source hint ===
Trace requirements via [stage->REQ-ID] tags

Usage: traceable-reqs.exe <COMMAND>


I have **admin** on the repo, and HEAD (936f00b, 2026-05-15) is newer than the v0.1.0 release (2026-05-04) — so HEAD likely has the escape fix. Plan: build HEAD for linux (gravity) + windows, cut release **v0.1.1**; CI downloads "latest" by pattern so it auto-picks it (no further ci.yml change). First clone + build locally + verify HEAD actually fixes it.


cd /c/Users/decid && rm -rf tr-build && gh repo clone BigscreenVR/traceable-reqs tr-build 2>&1 | tail -2 && cd /c/Users/decid/tr-build && grep -E '^version' Cargo.toml | head -1; echo "=== build release (win) ==="; cargo build --release 2>&1 | tail -4

Clone traceable-reqs HEAD + build windows release


Cloning into 'tr-build'...
grep: Cargo.toml: No such file or directory
=== build release (win) ===
error: could not find `Cargo.toml` in `C:\Users\decid\tr-build` or any parent directory
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


cd /c/Users/decid/tr-build && ls -la && echo "=== find manifests ==="; find . -maxdepth 3 \( -name Cargo.toml -o -name package.json -o -name go.mod -o -name "*.toml" \) 2>/dev/null | head; echo "=== how is it built? (CI/release) ==="; ls .github/workflows 2>/dev/null; head -60 .github/workflows/*.yml 2>/dev/null | head -60

Inspect traceable-reqs repo structure + build


total 94
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 .
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 ..
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 .git
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 .github
-rw-r--r-- 1 decid 197609   295 Jun  2 03:57 .gitignore
-rw-r--r-- 1 decid 197609  3001 Jun  2 03:57 AGENTS.md
-rw-r--r-- 1 decid 197609    12 Jun  2 03:57 CLAUDE.md
-rw-r--r-- 1 decid 197609  4457 Jun  2 03:57 README.md
-rw-r--r-- 1 decid 197609  7555 Jun  2 03:57 SKILL.md
-rw-r--r-- 1 decid 197609 26428 Jun  2 03:57 SPEC.md
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 example
drwxr-xr-x 1 decid 197609     0 Jun  2 03:57 rust
=== find manifests ===
./example/traceable-reqs.toml
./rust/Cargo.toml
./rust/traceable-reqs.toml
=== how is it built? (CI/release) ===
ci.yml
release.yml
==> .github/workflows/ci.yml <==
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: rust
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: rust
      - run: cargo fmt --check
      - run: cargo clippy --all-targets -- -D warnings
      - run: cargo test

  skill-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PyYAML
        run: python3 -m pip install --quiet pyyaml
      - name: Validate SKILL.md frontmatter
        run: |
          python3 - <<'PY'
          import sys, pathlib, yaml
          errs = 0
          checked = 0
          for p in sorted(pathlib.Path('.').rglob('SKILL.md')):
              checked += 1
              text = p.read_text(encoding='utf-8')
              if not text.startswith('---'):
                  print(f"{p}: missing leading '---' frontmatter delimiter")
                  errs += 1
                  continue
              parts = text.split('---', 2)
              if len(parts) < 3:
                  print(f"{p}: malformed frontmatter (no closing '---')")
                  errs += 1
                  continue
              try:
                  yaml.safe_load(parts[1])
              except yaml.YAMLError as e:
                  print(f"{p}: invalid YAML: {e}")
                  errs += 1
          if checked == 0:
              print("No SKILL.md files found")
              sys.exit(1)
          if errs:
              sys.exit(1)
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


Rust project is in `rust/`; there's a `release.yml`. The clean path: bump version, tag, push — let the release workflow build all platforms. Read `release.yml`.


cd /c/Users/decid/tr-build && cat .github/workflows/release.yml; echo "=== current version ==="; grep -E '^version' rust/Cargo.toml; echo "=== tags ==="; git tag | tail -5

Read release workflow + version + tags


name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
            artifact: traceable-reqs
            asset_suffix: linux-x86_64
          - os: windows-latest
            target: x86_64-pc-windows-msvc
            artifact: traceable-reqs.exe
            asset_suffix: windows-x86_64.exe
          - os: macos-latest
            target: aarch64-apple-darwin
            artifact: traceable-reqs
            asset_suffix: macos-arm64
    runs-on: ${{ matrix.os }}
    defaults:
      run:
        working-directory: rust
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
      - uses: Swatinem/rust-cache@v2
        with:
          workspaces: rust
      - run: cargo build --release --target ${{ matrix.target }}
      - name: Stage asset
        shell: bash
        run: |
          mkdir -p ../dist
          cp target/${{ matrix.target }}/release/${{ matrix.artifact }} \
             ../dist/traceable-reqs-${{ github.ref_name }}-${{ matrix.asset_suffix }}
      - uses: softprops/action-gh-release@v2
        with:
          files: dist/traceable-reqs-${{ github.ref_name }}-${{ matrix.asset_suffix }}
          fail_on_unmatched_files: true
=== current version ===
version = "0.1.0"
=== tags ===
v0.1.0
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


Release workflow builds all 3 platforms on a `v*` tag and names assets to match CI's `*linux-x86_64` pattern. Clean path: verify HEAD fixes it → bump version → tag → push → workflow publishes. First **verify HEAD honors the escape** (build `rust/` locally, run against spt-core's committed tree).


cd /c/Users/decid/tr-build/rust && cargo build --release 2>&1 | tail -3 && git stash push -u >/dev/null 2>&1 && echo "=== HEAD-built binary on committed tree ===" && /c/Users/decid/tr-build/rust/target/release/traceable-reqs.exe check --json 2>&1 | grep -E "findingCount|incompleteCount|completeCount"; /c/Users/decid/tr-build/rust/target/release/traceable-reqs.exe check >/dev/null 2>&1; echo "HEAD-built check exit=$?"; git stash pop >/dev/null 2>&1

Build HEAD + verify it honors the escape on committed tree


Error: Exit code 1
   Compiling toml v0.8.23
   Compiling traceable-reqs v0.1.0 (C:\Users\decid\tr-build\rust)
    Finished `release` profile [optimized] target(s) in 11.71s
=== HEAD-built binary on committed tree ===
    "completeCount": 27,
    "incompleteCount": 0,
    "findingCount": 0
HEAD-built check exit=0


That ran against traceable-reqs' *own* repo (27 reqs) — I was in the wrong dir. Re-run the HEAD-built binary against **spt-core's** committed tree.


git stash push -u -m wip >/dev/null 2>&1; echo "stashed"; /c/Users/decid/tr-build/rust/target/release/traceable-reqs.exe check --json 2>&1 | grep -E "requirementCount|completeCount|incompleteCount|findingCount"; /c/Users/decid/tr-build/rust/target/release/traceable-reqs.exe check >/dev/null 2>&1; echo "HEAD-built exit on spt-core committed tree=$?"; git stash pop >/dev/null 2>&1; echo "wip restored"

HEAD-built binary against spt-core committed tree


stashed
    "requirementCount": 116,
    "completeCount": 116,
    "incompleteCount": 0,
    "findingCount": 0
HEAD-built exit on spt-core committed tree=0
wip restored


Confirmed — **HEAD-built binary: 116/116, 0 findings, exit 0** on spt-core. HEAD has the fix. Now ship it: bump version → commit → tag → push (release workflow builds all 3 platforms). Bump `rust/Cargo.toml`.


1	[package]
2	name = "traceable-reqs"
3	version = "0.1.0"
4	edition = "2021"
5	description = "Requirements tracing CLI driven by a TOML manifest and [stage->REQ-ID] tags"
6	license = "Apache-2.0 OR MIT"

[package]
name = "traceable-reqs"
version = "0.1.0"
edition = "2021"
description = "Requirements tracing CLI driven by a TOML manifest and [stage->REQ-ID] tags"
license = "Apache-2.0 OR MIT"


Edit

name = "traceable-reqs"
version = "0.1.0"

name = "traceable-reqs"
version = "0.1.1"


The file C:\Users\decid\tr-build\rust\Cargo.toml has been updated successfully. (file state is current in your context — no need to Read it back)

name = "traceable-reqs"
version = "0.1.1"

[package]
name = "traceable-reqs"
version = "0.1.0"
edition = "2021"
description = "Requirements tracing CLI driven by a TOML manifest and [stage->REQ-ID] tags"
license = "Apache-2.0 OR MIT"

[dependencies]
clap = { version = "4", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
walkdir = "2"


Bash

cd /c/Users/decid/tr-build/rust && cargo build --release 2>&1 | tail -2 && cd /c/Users/decid/tr-build && git add rust/Cargo.toml rust/Cargo.lock && git status --short && git log --oneline -1

Refresh lock + stage version bump


   Compiling traceable-reqs v0.1.1 (C:\Users\decid\tr-build\rust)
    Finished `release` profile [optimized] target(s) in 3.21s
warning: in the working copy of 'rust/Cargo.lock', LF will be replaced by CRLF the next time Git touches it
M  rust/Cargo.lock
M  rust/Cargo.toml
936f00b Quote SKILL.md description to fix YAML frontmatter (#7) (#11)
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


Version 0.1.1 staged. Commit → push main → tag → push tag (triggers the 3-platform release build).


cd /c/Users/decid/tr-build && git commit -q -m "chore(release): v0.1.1

Cut a release from HEAD: includes the [<stage>->...] illustration-escape
handling so doc example tokens are not flagged as malformed tags. The
v0.1.0 release predates this, breaking downstream CI that pins it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>" && git push origin HEAD:main 2>&1 | tail -3 && git tag v0.1.1 && git push origin v0.1.1 2>&1 | tail -3

Commit, push main, tag v0.1.1, push tag


To https://github.com/BigscreenVR/traceable-reqs.git
   936f00b..6420384  HEAD -> main
To https://github.com/BigscreenVR/traceable-reqs.git
 * [new tag]         v0.1.1 -> v0.1.1
Shell cwd was reset to C:\Users\decid\Documents\projects\spt-core


Tag pushed — release workflow building all 3 platforms. Watch it publish.


sleep 8; RID=$(gh run list --repo BigscreenVR/traceable-reqs --workflow release.yml --limit 1 --json databaseId --jq '.[0].databaseId' 2>&1); echo "release run=$RID"; gh run watch "$RID" --repo BigscreenVR/traceable-reqs --exit-status --interval 20 2>&1 | tail -8; echo "EXIT=$?"

Watch traceable-reqs release build


release run=26815361698
build (ubuntu-latest, x86_64-unknown-linux-gnu, traceable-reqs, linux-x86_64): .github#2

! Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4, softprops/action-gh-release@v2. Actions will be forced to run with Node.js 24 by default starting June 16th, 2026. Node.js 20 will be removed from the runner on September 16th, 2026. Please check if updated versions of these actions are available that support Node.js 24. To opt into Node.js 24 now, set the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true environment variable on the runner or in your workflow file. Once Node.js 24 becomes the default, you can temporarily opt out by setting ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true. For more information see: https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/
build (windows-latest, x86_64-pc-windows-msvc, traceable-reqs.exe, windows-x86_64.exe): .github#3

- NOTICE: windows-latest requests are being redirected to windows-2025-vs2026 by June 15, 2026
build (windows-latest, x86_64-pc-windows-msvc, traceable-reqs.exe, windows-x86_64.exe): .github#1

EXIT=0


Release built (exit 0). Verify v0.1.1 release + linux asset, then re-trigger spt-core CI.


echo "=== v0.1.1 assets ==="; gh release view v0.1.1 --repo BigscreenVR/traceable-reqs --json tagName,assets --jq '.tagName, (.assets[].name)' 2>&1 | head; echo "=== latest release (what CI grabs) ==="; gh release view --repo BigscreenVR/traceable-reqs --json tagName --jq .tagName 2>&1

Verify v0.1.1 release assets + latest


=== v0.1.1 assets ===
v0.1.1
traceable-reqs-v0.1.1-linux-x86_64
traceable-reqs-v0.1.1-macos-arm64
traceable-reqs-v0.1.1-windows-x86_64.exe
=== latest release (what CI grabs) ===
v0.1.1


v0.1.1 published as **latest** with the linux asset matching CI's pattern. Re-run the failed traceability job on the last spt-core run (test matrix already passed).


gh run rerun 26814794557 --failed 2>&1 | tail -3; sleep 8; gh run watch 26814794557 --exit-status --interval 20 2>&1 | grep -iE "traceability|coverage|✓|X |Process completed|conclusion" | tail -12; echo "WATCH_EXIT=$?"

Rerun failed traceability job + watch


✓ test (windows-latest) in 2m50s (ID 79056153209)
  ✓ Set up job
  ✓ Run actions/checkout@v4
  ✓ Install Rust (stable + clippy)
  ✓ Cache cargo
  ✓ Build
  ✓ Test
  ✓ Clippy (deny warnings)
  ✓ Post Cache cargo
  ✓ Post Run actions/checkout@v4
  ✓ Complete job
traceability: .github#2
WATCH_EXIT=0


gh run view 26814794557 --json conclusion,status,jobs --jq '{status,conclusion, jobs: [.jobs[] | {name, conclusion}]}' 2>&1 | head -20

Final CI run conclusion per job


**All three jobs green — full CI success** (traceability ✓, test ubuntu ✓, test windows ✓). First fully-green run on the repo. Cleaning up the temp build dir + recording the infra knowledge.


rm -rf /c/Users/decid/tr-build /tmp/tr-released.exe /tmp/ci-repro.json /tmp/lj.json /tmp/failed.log /tmp/cilog.txt 2>/dev/null; echo "cleaned"; git status -sb | head -3

Remove temp build artifacts


cleaned
## dev-freeform...origin/dev-freeform
 M M3b-PLAN.md


Write

---
name: ci-traceability-gate
description: How spt-core CI's traceability job installs traceable-reqs (PAT secret + BigscreenVR release), and the v0.1.0-stale gotcha.
metadata:
  type: reference
---

spt-core CI (`.github/workflows/ci.yml`) has two jobs: **test** (ubuntu+windows matrix: build/test/clippy) and **traceability** (downloads the `traceable-reqs` binary, runs `./traceable-reqs check --json`, hard gate).

**Install seam (the part that broke):** the traceability job does `gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64'` (no version pin → grabs the **latest** release). `BigscreenVR/traceable-reqs` is **PRIVATE + cross-org**, so the default repo-scoped `GITHUB_TOKEN` can't read it ("release not found"). Fixed 2026-06-02 by using `GH_TOKEN: ${{ secrets.TRACEABLE_REQS_TOKEN }}` — a PAT (in SaberMage's account) with read access to that repo, stored as the `TRACEABLE_REQS_TOKEN` repo secret on SaberMage/spt-core.

**The v0.1.0-stale gotcha:** the released `v0.1.0` binary (2026-05-04) predates the `[<stage>->...]` *illustration-escape* feature, so it flagged the angle-bracketed example tokens in `docs/TRACEABILITY.md` as `must`-severity `parse_error` findings → exit 1. It passed locally only because the dev's locally-built binary was newer (and Windows CRLF masking). Fixed by cutting **v0.1.1** from BigscreenVR/traceable-reqs `main` (HEAD had the fix; bumped `rust/Cargo.toml` 0.1.0→0.1.1, pushed tag → the repo's `release.yml` builds linux/windows/macos and publishes). CI auto-picked it up (latest-release download). **Lesson:** the project's tag-doc convention can outrun the pinned binary — keep the traceable-reqs release ahead of `TRACEABILITY.md`/`CLAUDE.md` convention changes.

I (this account, SaberMage) have **admin** on `BigscreenVR/traceable-reqs` — can cut releases. The Rust source is in its `rust/` subdir. See [[cross-machine-test-rig]] for the gravity-linux build host.


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

---
name: ci-traceability-gate
description: "How spt-core CI's traceability job installs traceable-reqs (PAT secret + BigscreenVR release), and the v0.1.0-stale gotcha."
metadata:
  node_type: memory
  type: reference
  originSessionId: 884ebd12-8e23-4eea-819b-bf8aeaa031f5
---

spt-core CI (`.github/workflows/ci.yml`) has two jobs: **test** (ubuntu+windows matrix: build/test/clippy) and **traceability** (downloads the `traceable-reqs` binary, runs `./traceable-reqs check --json`, hard gate).

**Install seam (the part that broke):** the traceability job does `gh release download --repo BigscreenVR/traceable-reqs --pattern '*linux-x86_64'` (no version pin → grabs the **latest** release). `BigscreenVR/traceable-reqs` is **PRIVATE + cross-org**, so the default repo-scoped `GITHUB_TOKEN` can't read it ("release not found"). Fixed 2026-06-02 by using `GH_TOKEN: ${{ secrets.TRACEABLE_REQS_TOKEN }}` — a PAT (in SaberMage's account) with read access to that repo, stored as the `TRACEABLE_REQS_TOKEN` repo secret on SaberMage/spt-core.

**The v0.1.0-stale gotcha:** the released `v0.1.0` binary (2026-05-04) predates the `[<stage>->...]` *illustration-escape* feature, so it flagged the angle-bracketed example tokens in `docs/TRACEABILITY.md` as `must`-severity `parse_error` findings → exit 1. It passed locally only because the dev's locally-built binary was newer (and Windows CRLF masking). Fixed by cutting **v0.1.1** from BigscreenVR/traceable-reqs `main` (HEAD had the fix; bumped `rust/Cargo.toml` 0.1.0→0.1.1, pushed tag → the repo's `release.yml` builds linux/windows/macos and publishes). CI auto-picked it up (latest-release download). **Lesson:** the project's tag-doc convention can outrun the pinned binary — keep the traceable-reqs release ahead of `TRACEABILITY.md`/`CLAUDE.md` convention changes.

I (this account, SaberMage) have **admin** on `BigscreenVR/traceable-reqs` — can cut releases. The Rust source is in its `rust/` subdir. See [[cross-machine-test-rig]] for the gravity-linux build host.


Edit

# 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.

# 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.


<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>

Error: File has not been read yet. Read it first before writing to it.


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

# 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.


- [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.

- [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.


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)

- [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.

# 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.


## CI fully green ✓

```
traceability       ✓ success
test (ubuntu)      ✓ success
test (windows)     ✓ success
```

First all-green run on `SaberMage/spt-core`. Path to get there:

1. **PAT secret** (`TRACEABLE_REQS_TOKEN`) — unblocked the cross-org private binary download. `ci.yml` committed + pushed.
2. **Root cause of the remaining 7 failures:** the pinned `traceable-reqs` **v0.1.0** predated the `[<stage>->...]` doc-escape convention, so it flagged `docs/TRACEABILITY.md`'s example tokens as `must` errors (masked locally by a newer local binary + CRLF). Coverage itself was always 116/116.
3. **Shipped v0.1.1** of `BigscreenVR/traceable-reqs`: HEAD already had the fix (verified it gives 0 findings on spt-core's tree) → bumped `rust/Cargo.toml` → tagged `v0.1.1` → its release workflow built linux/windows/macos. CI downloads "latest" by pattern, so it auto-picked v0.1.1. No further `ci.yml` change.

Temp build dir cleaned. Recorded the whole traceability-gate setup (PAT secret + the stale-binary gotcha + admin access) to memory for future sessions.

Current state:
- `dev-freeform` pushed through `5c26a4b`, CI green.
- `M3b-PLAN.md` rewrite still **uncommitted** in your tree (the full task table from earlier).

Next: want me to **commit `M3b-PLAN.md` and start B0** (scaffold `spt-daemon` + versioned IPC), or anything else first?


commit it, then /commune with immediate next steps and broad summary of the project's status + end goal. we'll resume in the next session --> finally, perform /self-clear


<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.


I'll commit M3b-PLAN.md, then commune, then self-clear. First the commit.


Bash

git add M3b-PLAN.md && git commit -q -m "docs(M3b): flesh M3b-PLAN.md from stub into full task table

Full just-in-time plan for the spt-daemon broker/brain milestone
(B0-B9): versioned-IPC scaffold, broker kernel, brain + gapless
handoff, consolidation, daemon-authoritative liveness, idempotent
boundary, auto-start + in-memory startup, orphan-watch, digest
daemon-half (REQ-TERM-4 int), activation + E2E. Derived from ADR-0004
(broker/brain split + ownership table + closed spike gaps), CONTEXT
daemon model, and a seam map of the interim no-daemon hosting the
daemon replaces.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>" && git log --oneline -3

Commit M3b-PLAN.md


7db111f docs(M3b): flesh M3b-PLAN.md from stub into full task table
5c26a4b ci: install traceable-reqs with a PAT secret (cross-org private repo)
a32b071 fix(store): concurrent SQLite openers fail with 'database is locked' (4.7)


Committed (`7db111f`). Now the commune — dropping `.claude/doyle-commune.md` per the documented mechanism, with next steps + status + end goal.


Write

# Commune — doyle → doyle-psyche (2026-06-02, branch dev-freeform)

## Where we are this session

**M3a SHIPPED** — `spt-term`, the session-surface mechanism (the broker's PTY half). 7 atomic commits (A0–A6), all OS-validated on Windows (ConPTY) + Linux (forkpty via gravity-linux):
- A1 `SessionSurface` trait + native PTY backend (ConPTY/forkpty via portable-pty), resize behind master lock.
- A2 ConPTY-DSR auto-answer drain pump (no-EOF-while-writer-held discipline). Found Win11 26200 ConPTY doesn't emit `ESC[6n` for short cmds → proved the auto-answer by synthetic injection, not host behavior.
- A3 send-keys/send-line injection. Found a real ConPTY race: Ctrl-C dropped if sent before child installs handler → readiness handshake.
- A4 bounded byte-stream (OutputStream over sync_channel → backpressure).
- A5 PTY-digest parser primitive (ADR-0008): adapter-supplied patterns in, structured source-tagged turns out; ANSI-stripped, tail-wins repaint tolerance.
- REQ-TERM-1/2/3/4 + REQ-HAZARD-CONPTY-DSR activated.

**Bonus fixes (the session's surprise depth):**
- Cross-OS validation exposed **8 pre-existing tests broken on Linux/CI** (spt-live + spt-runtime) — `cfg(unix)` manifest fixtures with bad TOML-vs-tokenizer quoting, never caught on the Windows dev host. Fixed.
- And a **real production concurrency bug** behind the "flaky" `two_agents_exchange_message_tcp_and_spool`: SQLite `database is locked` because `busy_timeout` was set *after* the `journal_mode=WAL` switch (which bypasses the busy-handler anyway). Fixed with a shared `spt_store::db::tune_connection` (busy_timeout first, WAL-with-bounded-retry) + new hazard REQ-HAZARD-REGISTRY-CONCURRENT (KNOWN-HAZARDS 4.7) + 16-thread regression test. killer_quickstart 4/5-FAIL → 12/12-PASS on Linux.

**CI is now FULLY GREEN for the first time** (test ubuntu ✓ / test windows ✓ / traceability ✓). Two CI-infra fixes: a `TRACEABLE_REQS_TOKEN` PAT secret (cross-org private binary download), and **cut traceable-reqs v0.1.1** on BigscreenVR (the pinned v0.1.0 predated the `[<stage>->...]` doc-escape and flagged TRACEABILITY.md examples). See memory `ci-traceability-gate.md` — I have admin to cut those releases.

**M3b planned, not started.** `M3b-PLAN.md` fleshed from stub into a full B0–B9 task table (committed 7db111f).

## Immediate next steps (resume here)

**Execute M3b, starting B0.** M3b = the `spt-daemon` broker/brain process (ADR-0004). The hard, load-bearing idea: two real processes — **broker** (stable kernel: holds PTYs from spt-term + harness children + sockets, NO logic) and **brain** (restartable logic) — over a **versioned local IPC**, so a brain-only self-update swaps logic with zero endpoint interruption. Spikes #1/#3/#5/#6 already proved the shape on both OSes.

Order (full detail in `M3b-PLAN.md`):
- **B0** scaffold `crates/spt-daemon` (above spt-live, below spt) + the versioned IPC transport (named-pipe/UDS behind one trait, forward-compat frame schema, version handshake). ← START HERE
- B1 broker kernel → B2 brain + **gapless handoff** (the milestone's proof-gate: kill brain ≥10×, child+stream survive; `gen_start=now()`) → B3 consolidation (fold listen/pulse/Psyche loops into the brain) → B4 daemon-authoritative liveness → B5 idempotent boundary (Spike #6) → B6 auto-start + in-memory startup (retire the seed *file*) → B7 orphan-watch → B8 digest daemon-half (completes REQ-TERM-4 `int`) → B9 activation + brain-restart E2E + docs + M3c stub.

Discipline that's working: each task = one atomic commit, evidence-tagged, `traceable-reqs check` green, validated on BOTH OSes (Windows local + gravity-linux) before the next. Reuse `spt-term::PtySession` for broker PTYs; re-host (don't rewrite) the pure spt-live seams.

Binding constraints: broker holds ZERO logic (resist scope creep); version the IPC frame from byte one (forward-compat retrofits are expensive); B2 gapless-handoff is a gate not polish.

## Project status (broad) + end goal

**spt-core** = harness-independent core for an agent ecosystem — clean-room rebuild of `claude_skill_owl`. Rust crates + one `spt` binary. **End goal:** the *same* agent runs natively across all of a user's machines with a synced mind, reachable + operable from anywhere, seamless self-update, zero-config cross-machine messaging. First thing built atop it: a rebuilt `spt` plugin at parity with modern SPT.

Milestone map: M0 (proto+store) ✅ · M1 (msg) ✅ · M2a (runtime/harness contract) ✅ · M2b (live-agent lifecycle) ✅ · **M3a (spt-term) ✅** · **M3b (spt-daemon) ← NEXT** · M3c (self-update) · M4 (spt-net: Iroh/mDNS/pairing + multi-subnet + cross-node Psyche sync — the real proof: drive an agent on machine A from machine B) · M5 (Shells, presence, gated capabilities). 9 ADRs. Phase 0 spike-gate complete.

Layering (acyclic): `spt-proto → spt-store → spt-msg → {spt-net, spt-term, spt-runtime} → spt-live → spt-daemon → spt`. Binding rules: requirement traceability (`traceable-reqs.toml` authoritative, tag evidence in-commit), honor KNOWN-HAZARDS invariants, copy-verbatim sister's stable wire formats / clean-room everything else.

State: branch `dev-freeform`, head 7db111f, pushed, CI green, all reqs green (116/116). Resume by reading M3b-PLAN.md + starting B0.