samosunaz/samuel

Triage, verify, and resolve incoming PR comments — apply fixes, reply, resolve threads, close each pass with a Resolution marker comment, re-request review. Incremental: scopes to feedback since the last pass. Author side of the PR review gate. Trigger on 'address pr comments', 'address review feedback', 'resolve review threads', 'reply to review'.

Read-only cross-artifact consistency check across spec, research, plan, tasks, journal, and constitution. Severity-tagged findings, no auto-edits. Trigger on 'analyze', 'consistency check', before implementing a non-trivial feature.

Document an endpoint the backend built, for the client(s) that consume it — web frontend and/or native mobile (iOS/Android). Emits TS + Swift/Kotlin types. Output is an inline copy-paste block by default. Trigger on 'api contract', 'document endpoint', 'contract for frontend/mobile'.

Spec an endpoint a client needs from the backend, from the web frontend OR native mobile (iOS/Android) perspective. Output is an inline copy-paste block by default. Trigger on 'api request', 'i need an endpoint', 'request endpoint', 'spec for backend', 'new endpoint from front/mobile'.

Document codebase as-is through parallel sub-agent research and synthesis. Use when user asks to understand, explore, or document how code works without making changes.

Drive the pipeline unattended phase-by-phase. Can bootstrap from an item id, drive research→…→validate, and (in --ship mode) open a draft PR. Can be fired automatically by GitHub (schedule / issue-labeled) — see reference/automated-trigger.md. Trigger on 'conductor', 'run pipeline', 'run the pipeline unattended', overnight/autonomous runs paired with /goal.

Create git commits with user approval and no AI attribution. Reviews changes, plans atomic commits following conventional commits, and executes upon confirmation.

Ratify the repo's CONSTITUTION.md (3-5 non-negotiable principles, semver, governance) at v1.0.0. Optional — the pipeline degrades gracefully without it. Trigger on 'create constitution', 'ratify principles', 'initial constitution'.

Generate a repo's schema-v1 REVIEW.md — deterministic evidence digest (repo type, gate signals, CI job names, validation/journal findings, self-review history) + semantic derivation of repo-specific rules, cited per bullet. Existing REVIEW.md → --check conformance report only. Trigger on 'create review md', 'generate REVIEW.md', 'review overrides'.

Close the loop — open a PR (Closes #N), mark the item done, and clean up. Supports --draft for autonomous runs. Trigger on 'done', 'finished', 'ship it', 'open the PR'.

Create or update a living feature dossier — enriched markdown + Mermaid diagrams/flows — in a versioned product catalog. For big features that change product behavior; reference for humans and AI before future modifications. Output language configurable (--lang, default es). Trigger on 'feature dossier', 'document this feature', 'document this capability', 'feature catalog', 'update dossier'.

Map-vs-territory audit — surface known unknowns, unknown knowns, and unknown unknowns of an idea, Issue, or diff before they get expensive. Modes: audit (default), preflight (Issue N), teach (--teach «domain»), quiz (--quiz [N]). Standalone — no task-context required. Trigger on 'find unknowns', 'unknowns', 'blind spot', 'what am i missing', 'quiz me'.

Execute a self-contained Executor Plan step-by-step with human verification between phases, keeping a living Implementation Notes journal. Use when ready to implement a planned item.

Initialize a new indie project: vision doc, MVP scope, tech decisions, initial task breakdown. Trigger on 'kickoff', 'new project', 'start project'.

Mermaid diagram style standard: semantic shapes + emoji vocabulary + classDef palette. Invoke before authoring any Mermaid diagram (dossier, contract, RFC, Issue/PR). Trigger on 'mermaid', 'flow diagram', 'diagram this', 'mermaid standard'.

Refine a natural-language description of a desired animation, transition, or motion effect — optionally with screenshots, diagrams, GIFs, or reference videos — into a precise, implementation-ready Motion Brief using canonical animation nomenclature. Use when the user describes motion loosely ("the cards should kind of cascade in", "make it feel bouncy like iOS"), shares a visual reference of an effect to reproduce, or asks to polish an animation idea into an agent-ready prompt.

Pull the next prioritized work item (GitHub Issues). Trigger on 'next', 'next task', 'what is next', 'pull task'.

Create a self-contained plan (human Brief + Executor Plan) through 5 interactive phases with forced human checkpoints. Writes to the GitHub Issue body. Use when planning a feature, refactor, or initiative before implementation.

Review a PR for bugs, security, and logic errors. High-signal only. Trigger on 'review pr', 'code review', 'audit this pr'.

Personal progress dashboard: item status, velocity, and blockers from GitHub. Trigger on 'progress', 'dashboard', 'where do we stand', 'status'.

Iterate on an existing plan based on feedback. Surgical edits to the Executor Plan (Steps, scope, criteria, approach). Trigger on 'iterate plan', 'change the plan', 'adjust the phases'.

Remove AI-generated code slop from the current branch. Scans diff against base branch for unnecessary comments, defensive code, type hacks, and style inconsistencies introduced by AI tools.

Substrate drift detector for samuel consumer repos: deterministic checks (samuel.md, gh auth/repo, pipeline+roadmap+promo labels, .claude gitignored, CLAUDE.md; optional: constitution, REVIEW.md, conductor heartbeat, release-please, squash merge, TL;DR templates, cross-session messaging) + a semantic pass over CLAUDE.md. Report-only. Trigger on 'repo audit', 'audit repo', 'substrate drift', 'drift check'.

Personal retrospective: analyze what worked, what didn't, and what to change, from GitHub + git history. Trigger on 'retro', 'retrospective', 'lessons learned'.

Product Ownership session — read the product's real state and propose prioritized bets (what to build next and why), persisted as roadmap:* issues ready to promote into the pipeline. Discovery, upstream of plan. Trigger on 'roadmap', 'product direction', 'what to build next', 'what is next for the product', 'upcoming capabilities', 'opportunities', 'where to take this'.

Create or resume handoff documents for context compaction between sessions. Use when context is large, switching sessions, or resuming previous work.

Generate a Spec doc (User Stories P1/P2/P3, FR-### MUST, SC-### measurable, Edge Cases) with up to 5 clarifications. Optional — only when spec_required. Trigger on 'create spec', 'write the spec', or after /samuel:start-task when spec_required.

Pick a work item (GitHub Issue), create a branch, and inject task context. Use when a dev is ready to start implementing an item.

Orchestrate Claude Code agent teams (multi-session parallel agents with shared task list and inter-agent messaging) for code review, debugging with competing hypotheses, multi-module features, or multi-angle research. Use whenever the work has independent parallelizable streams, when teammates need to challenge each other's findings, or when the user mentions 'agent team', 'spawn teammates', 'swarm', 'parallel review', 'team mode', 'orchestrate agents'. Different from /samuel:codebase-documentation (single-session parallel subagents) — use this when teammates must communicate, persist across turns, or be addressed individually.

Prose standard: rewrite a message to Simplified Technical English — one reading per sentence, no filler, no abstract jargon. Targets the last assistant message by default, or pasted text / a file path. Never touches code, commands, or quoted output. Trigger on 'tldr', 'bro', 'rewrite that', 'make it simple', 'less jargon', 'cut the filler', 'too verbose'.

Amend the repo's CONSTITUTION.md. Semver versioning (PATCH / MINOR / MAJOR), Sync Impact Report, updates Last Amended. Reads existing file at repo root, proposes surgical edits, applies after user approval.

Validate the implementation against the plan, verify acceptance criteria, run the project gate, resolve & seal the journal, and analyze documentation impact. Mandatory final step before done.

Prepare the open backlog for a wave run: sweep pipeline issues, infer real inter-issue dependencies from their Executor Plans, declare the missing native blockedBy edges (human-approved), and hand the ready set to /samuel:waves. Trigger on 'wave prep', 'prepare waves', 'prepare the backlog for waves', 'backlog edges', 'which issues can run in parallel'.

Attended multi-issue coordinator: executes a set of pipeline:ready issues in parallel waves computed from GitHub's native blockedBy graph — one Orca worktree + worker per issue (Codex default, claude-conductor variant), draft PRs, human merge releases the next wave. Trigger on 'waves', 'launch waves', 'run the epic', 'run the epic in parallel', 'wave run'.