Skip to content

Publish accumulated Stack skills and routing #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thecolormaroun merged 1 commit into from
Jul 14, 2026
Merged

Publish accumulated Stack skills and routing #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ Runs:

| Skill | Emoji | What it does |
|-------|-------|-------------|
| `agent-operating-stack/` | 🧭 | Routes broad work across product/design, engineering, agent orchestration, and Hermes-safe verification |
| `mega-workflow/` | 🚀 | Full pipeline orchestrator — product → design → build → verify → ship |
| `ideate/` | 💡 | Idea validation suite — YC pushback, scope review, design + eng feasibility |
| `departments/` | 🏢 | Simpler pipeline — CPO → CDO → /lfg |
Expand Down Expand Up @@ -143,6 +144,16 @@ Run these after writing code to clean up before shipping.
| `reclaude/` | Refactor bloated CLAUDE.md files using progressive disclosure |
| `gemini-review/` | Read-only Google AI / Antigravity second-model review over a git diff |

### Agent Workflow Skills

| Skill | What it does | Source |
|-------|-------------|--------|
| `agent-operating-stack/` | Routes Emil design craft, imported upstream skills, Stack-native workflows, and Hermes/Mookie verification gates | [Meng To post](https://x.com/MengTo/status/2075221793925955897) |
| `matt-*/` | 22 namespaced Matt Pocock engineering/productivity skill imports | [mattpocock/skills](https://github.com/mattpocock/skills) |
| `david-*/` | 30 namespaced David Ondrej agent skill imports | [davidondrej/skills](https://github.com/davidondrej/skills) |
| `agent-verification-ladder/` | Selects the right proof level before claiming agent work is complete | Stack/Hermes local workflow |
| `goal-validation-threads/` | Validates candidate skills/workflows in fresh goal threads | Stack/Hermes local workflow |

---

## Studio Skill Graph
Expand Down Expand Up @@ -187,6 +198,9 @@ Entry point: `skills/studio/_graph/studio.moc.md`
│ │ └── react-doctor/
│ ├── studio/ # Studio Skill Graph (90+ files)
│ │ └── _graph/
│ ├── agent-operating-stack/
│ ├── matt-*/ # Namespaced Matt Pocock skill imports
│ ├── david-*/ # Namespaced David Ondrej skill imports
│ ├── emil-design-eng/
│ ├── review-animations/
│ ├── make-interfaces-feel-better/
Expand Down
7 changes: 7 additions & 0 deletions config/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,10 @@ Motion defaults:

Anti-slop guardrails:
- `skills/studio/_graph/design/system/studio.design.system.anti-slop.md`

## Agent Operating Stack

When a request is broad, multi-step, agent-orchestration-heavy, based on an external workflow source, or asks how Hermes/Mookie should leverage Stack, consult:
- `skills/agent-operating-stack/SKILL.md`

Use it to choose the product/design, engineering, `/goal`, subagent, Hermes-native migration, and verification lane before acting.
104 changes: 104 additions & 0 deletions skills/agent-operating-stack/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
name: agent-operating-stack
description: "Route broad Stack/Hermes work through the right design, engineering, agent-orchestration, and verification loops. Use when adding external agent workflow ideas to Maroun's stack, choosing between ideate/departments/mega/tdd/review skills, drafting long-running /goal contracts, delegating subagents, or making Hermes/Mookie leverage Stack without unsafe core patches or unverified runtime claims."
---

# Agent Operating Stack

## Overview

Use this skill as the router for Maroun's operating stack: product/design pipelines, Matt Pocock-style engineering loops, David Ondrej-style agent orchestration, Emil Kowalski-style design engineering, and Hermes/Mookie safety gates. It turns broad requests into an executable loop with a source of truth, hard boundaries, and a verification gate.

Read [references/imported-skills.md](references/imported-skills.md) when you need the exact list of imported upstream skills. Read [references/source-map.md](references/source-map.md) when you need upstream provenance, license posture, or the detailed mapping from the Meng To post and linked repos into local Stack skills. Read [references/execution-routing.md](references/execution-routing.md) before any multi-agent, multi-reviewer, or long-running Hermes workflow.

## Operating Loop

For broad, urgent, multi-step, or "add this to the stack" requests:

1. Name the durable outcome in one sentence.
2. Identify the source of truth: repo files, issue, plan, UI, docs, screenshots, live service state, or an upstream source.
3. Name hard boundaries: what must not be mutated, weakened, promoted, exposed, or claimed as complete.
4. Choose the workflow lane below.
5. Choose the verification gate before acting.
6. Keep working until the gate passes or the same blocker repeats enough to mark blocked.
7. Close out with changed files, proof used, residual risk, and the next useful gate.

## Workflow Lanes

### New Product Or Feature

- Vague idea or startup wedge: use `ideate`.
- Brain dump needs a product/design spec: use `departments`.
- Build from idea through PR-quality verification: use `mega-workflow`.
- UI-heavy work: use `cdo`, then `emil-design-eng` and `review-animations` before shipping.

### Software Engineering

Use the Matt-derived loop as the default discipline:

- Concrete imported router: `$matt-ask-matt`.
- Ambiguous implementation: align vocabulary and decisions before coding. Create or update `CONTEXT.md`/ADRs only when the repo already uses them or the decision is genuinely durable.
- Single-session concrete work: use `$matt-implement` and `$matt-tdd` for small vertical slices where a real seam exists.
- Multi-session work: use `$matt-to-spec` and `$matt-to-tickets`; keep each ticket independently verifiable.
- Foggy or huge work: use `$matt-wayfinder`; map investigation decisions first and do not collapse planning and execution unless the destination is already clear.
- Bug or regression: use `$matt-diagnosing-bugs`; build a red-capable feedback loop before theorizing, then minimize, instrument, fix, and regression-test.
- Review: use `$matt-code-review`; separate standards/design quality from spec faithfulness so one axis does not mask the other.

### Agent Orchestration

Use the David-derived loop only when delegation or persistence is actually useful:

- Model routing: use Sol/high for orchestration and final synthesis, Terra/medium for implementation, Terra/high for risk review, and Luna/medium for bounded exploration. Do not let executors inherit Sol implicitly.
- `/goal`: use `$david-goal-loop` only for work with a concrete stop condition and validation command. Include objective, read-first files, constraints, validation, documentation, checkpoints, and stop condition.
- Subagents: use `$david-codex-subagent` only for self-contained work with the minimum required context, owned files/worktree isolation, and a clear definition of done. Prefer an artifact path or compact task packet over copying the full parent conversation. Review their diffs or artifacts before trusting them.
- Handoffs: use `$david-handoff` or `$matt-handoff` when a session must continue elsewhere; do not rely on chat memory alone for multi-session continuity.
- Scheduling: use `$david-agent-self-scheduling` for general agent scheduling guidance, but prefer Hermes' built-in scheduler for Hermes work. Ask before new cron, LaunchAgents, credential grants, paid services, or production-state changes.

Apply the quota and fan-out limits in `references/execution-routing.md`. External skills remain upstream-owned; Stack controls when they are invoked and prevents automatic implementation, simplification, full-review, and validator waves from stacking mechanically.

### Hermes And Mookie

When Hermes, Mookie, GBrain, Telegram gateway, Google/Gmail/Calendar, or local plugins are in scope:

- Read the local Hermes source of truth first: `~/hermes/MOOKIE.md`, `~/hermes/KNOWLEDGE.md`, `~/hermes/PILOT.md`, and the relevant plan/report under `docs/plans/` or `tmp/`.
- Prefer Hermes-native extension surfaces: plugins, hooks, config, root-level tests, skills, local scripts, and scheduler jobs.
- Do not preserve private Hermes core patches unless the user explicitly accepts the local patch plus a removal/upstream gate.
- Separate runtime liveness from auth health, queue health, lock state, and browser/account access.
- For Google/Gmail/Calendar claims, verify `gog auth list --check` or the local preflight before claiming live access.
- Preserve Sol/high for the user-facing Mookie root when its quality is valuable, but route delegated implementation to Terra and lightweight/background work to Luna. Control long-context growth and repeated cache reads instead of solving every quota problem by downgrading the interactive model.
- Use `hermes-native-patch-migration` for patch migration and `agent-verification-ladder` for proof selection.

## Verification Gates

Pick the lowest proof level that can genuinely prove the claim:

- Artifact: exact file, diff, report, source map, plan, screenshot, or output exists and matches the request.
- Command: focused test, lint, typecheck, parser, smoke command, or update dry-run passes.
- State: live service, branch, queue, LaunchAgent, gateway, deployment, auth, or lock state is checked.
- Browser/UI: `agent-browser` screenshot or smoke when user-visible rendering matters.
- Independent: focused validation thread or isolated worktree for broad, risky, or reusable workflow changes.

Never turn "no error shown" into proof. Name unproven gates explicitly.

## Hermes-Ready Skill Rules

When adding a reusable workflow to Stack for Hermes or Codex to leverage:

- Create or update a discoverable skill under `skills/<name>/`.
- Include `agents/openai.yaml` with a short default prompt using `$skill-name`.
- Keep `SKILL.md` lean; move provenance and detailed mapping into `references/`.
- Preserve source pins and license posture for imported/adapted upstream ideas.
- Prefix upstream imports when names would collide with Stack-native skills, as with `matt-*` and `david-*`.
- Prefer Stack-native skills for Maroun-specific behavior and imported skills for the upstream workflow they encode.
- Add README/config routing only when it improves discovery for future agents.

## Closeout Format

Report:

- workflow lane chosen;
- files changed;
- upstream sources or local surfaces inspected;
- verification command or artifact;
- Hermes/Mookie gate status when relevant;
- residual risk and next smallest gate.
4 changes: 4 additions & 0 deletions skills/agent-operating-stack/agents/openai.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Agent Operating Stack"
short_description: "Route design, code, and agent loops"
default_prompt: "Use $agent-operating-stack to choose the right Stack/Hermes operating loop and verification gate."
90 changes: 90 additions & 0 deletions skills/agent-operating-stack/references/execution-routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Agent Execution Routing

This is Stack's durable composition policy. It controls how local workflows use
external skills and agents; it does not modify vendored or upstream skill files.

## Model roles

| Role | Model | Reasoning | Use |
| --- | --- | --- | --- |
| Orchestrator | `gpt-5.6-sol` | high | Decomposition, architecture, conflict resolution, final synthesis |
| Worker | `gpt-5.6-terra` | medium | Implementation, tests, general engineering |
| Reviewer | `gpt-5.6-terra` | high | Correctness, security, contracts, regression risk |
| Explorer | `gpt-5.6-luna` | medium | Repository mapping, extraction, summaries, bounded research |

Use Sol explicitly at the root. Executors must be pinned to Terra or Luna and
must not inherit Sol or `xhigh` reasoning from the parent.

For Hermes, the interactive Mookie root may remain on Sol/high when the user
values the quality. That does not make Sol the right default for subagents,
cron, compression, extraction, or catalog work.

## Quota preflight

If `~/Codex/scripts/codex-quota-preflight.sh` exists, run it before
any multi-agent or multi-reviewer wave. Otherwise fail closed to one Terra/Luna
executor until the live quota is known.

| Rolling quota used | Mode | Maximum executors |
| ---: | --- | ---: |
| below 50% | normal | 3 |
| 50-69% | constrained | 2 |
| 70-84% | single | 1 |
| 85% or higher | pause | 0 |
| unknown | single | 1 |

Pause mode permits deterministic local work but no new model executors unless
the user explicitly overrides the quota gate.

## Dispatch limits

- Maximum three open agent threads and nesting depth one.
- Children never spawn children.
- Use no inherited conversation for self-contained packets. If recent context
is genuinely required, pass at most the latest three turns; never clone the
entire parent conversation.
- Give every executor a bounded goal, paths, boundaries, deliverable, and
verification command.
- Allow one follow-up per executor, then close it or start a fresh narrower
packet.
- Run one review wave. A second wave requires a validated P0/P1 finding or an
explicit request for deep review.

## External workflow composition

Keep `ce-work`, `ce-simplify-code`, `ce-code-review`, and other external skills
unchanged. Stack owns their composition:

- Run trivial or small implementation inline.
- Use Terra workers only for independent bounded implementation units.
- Run simplification once at a meaningful phase boundary. In constrained or
single mode, combine reuse, quality, and efficiency into one inline pass.
- Default code review to one targeted Terra/high reviewer selected by actual
risk. Add a second reviewer only for a distinct high-risk surface.
- Use a full multi-reviewer workflow only in normal mode for explicit deep
review or high-risk authentication, payments, destructive data changes,
public contracts, concurrency, or verification machinery.
- Validate strong P0/P1 findings independently; do not launch a validator for
every weak P2/P3 observation.
- Do not automatically stack implementation fan-out, simplification reviewers,
a full review roster, and per-finding validators.

## Hermes context hygiene

Sol quality can stay at the user-facing root while token amplification is
controlled separately:

- Start a new session when the subject changes materially instead of growing a
single Telegram thread indefinitely.
- Inspect `/usage` during long sessions and use `/compress` before repeated
large-context calls dominate usage.
- Prefer the normal compression threshold over an 85% Codex-family autoraise
when quota conservation matters.
- Keep compression, extraction, cron, and delegated support work on Luna or
Terra.

## Closeout gate

Before claiming an orchestrated workflow complete, verify the role/model used
by each child, peak executor count, nesting depth, review-wave count, focused
tests or artifacts, and the post-run quota state.
70 changes: 70 additions & 0 deletions skills/agent-operating-stack/references/imported-skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Imported Upstream Skills

These are the concrete namespaced imports added from the Meng To recommendation. They are prefixed to avoid overwriting Stack-native skills and to keep upstream provenance clear.

## Matt Pocock Engineering And Productivity Skills

| Local skill | Upstream skill | Upstream path |
| --- | --- | --- |
| `$matt-ask-matt` | `ask-matt` | `skills/engineering/ask-matt` |
| `$matt-code-review` | `code-review` | `skills/engineering/code-review` |
| `$matt-codebase-design` | `codebase-design` | `skills/engineering/codebase-design` |
| `$matt-diagnosing-bugs` | `diagnosing-bugs` | `skills/engineering/diagnosing-bugs` |
| `$matt-domain-modeling` | `domain-modeling` | `skills/engineering/domain-modeling` |
| `$matt-grill-with-docs` | `grill-with-docs` | `skills/engineering/grill-with-docs` |
| `$matt-implement` | `implement` | `skills/engineering/implement` |
| `$matt-improve-codebase-architecture` | `improve-codebase-architecture` | `skills/engineering/improve-codebase-architecture` |
| `$matt-prototype` | `prototype` | `skills/engineering/prototype` |
| `$matt-research` | `research` | `skills/engineering/research` |
| `$matt-resolving-merge-conflicts` | `resolving-merge-conflicts` | `skills/engineering/resolving-merge-conflicts` |
| `$matt-setup-matt-pocock-skills` | `setup-matt-pocock-skills` | `skills/engineering/setup-matt-pocock-skills` |
| `$matt-tdd` | `tdd` | `skills/engineering/tdd` |
| `$matt-to-spec` | `to-spec` | `skills/engineering/to-spec` |
| `$matt-to-tickets` | `to-tickets` | `skills/engineering/to-tickets` |
| `$matt-triage` | `triage` | `skills/engineering/triage` |
| `$matt-wayfinder` | `wayfinder` | `skills/engineering/wayfinder` |
| `$matt-grill-me` | `grill-me` | `skills/productivity/grill-me` |
| `$matt-grilling` | `grilling` | `skills/productivity/grilling` |
| `$matt-handoff` | `handoff` | `skills/productivity/handoff` |
| `$matt-teach` | `teach` | `skills/productivity/teach` |
| `$matt-writing-great-skills` | `writing-great-skills` | `skills/productivity/writing-great-skills` |

## David Ondrej Agent Skills

| Local skill | Upstream skill | Upstream path |
| --- | --- | --- |
| `$david-agent-self-scheduling` | `agent-self-scheduling` | `skills/agent-orchestration/agent-self-scheduling` |
| `$david-cmux` | `cmux` | `skills/agent-orchestration/cmux` |
| `$david-codex-subagent` | `codex-subagent` | `skills/agent-orchestration/codex-subagent` |
| `$david-fable-safe-prompt` | `fable-safe-prompt` | `skills/agent-orchestration/fable-safe-prompt` |
| `$david-goal-loop` | `goal-loop` | `skills/agent-orchestration/goal-loop` |
| `$david-handoff` | `handoff` | `skills/agent-orchestration/handoff` |
| `$david-run-deep-swe` | `run-deep-swe` | `skills/agent-orchestration/run-deep-swe` |
| `$david-anti-sleep` | `anti-sleep` | `skills/ops-and-setup/anti-sleep` |
| `$david-create-readonly-db-role` | `create-readonly-db-role` | `skills/ops-and-setup/create-readonly-db-role` |
| `$david-cyber-audit` | `cyber-audit` | `skills/ops-and-setup/cyber-audit` |
| `$david-google-safe-browsing` | `google-safe-browsing` | `skills/ops-and-setup/google-safe-browsing` |
| `$david-pi-custom-model` | `pi-custom-model` | `skills/ops-and-setup/pi-custom-model` |
| `$david-setup-help` | `setup-help` | `skills/ops-and-setup/setup-help` |
| `$david-browser-harness` | `browser-harness` | `skills/research-and-web/browser-harness` |
| `$david-deep-research` | `deep-research` | `skills/research-and-web/deep-research` |
| `$david-deepapi` | `deepapi` | `skills/research-and-web/deepapi` |
| `$david-online-shopping` | `online-shopping` | `skills/research-and-web/online-shopping` |
| `$david-pi-web-search` | `pi-web-search` | `skills/research-and-web/pi-web-search` |
| `$david-research-prompt` | `research-prompt` | `skills/research-and-web/research-prompt` |
| `$david-youtube-transcript` | `youtube-transcript` | `skills/research-and-web/youtube-transcript` |
| `$david-distribute-skill-to-all-agents` | `distribute-skill-to-all-agents` | `skills/skill-authoring/distribute-skill-to-all-agents` |
| `$david-effective-agent-skills` | `effective-agent-skills` | `skills/skill-authoring/effective-agent-skills` |
| `$david-folder-specific-claude-and-agents-md` | `folder-specific-claude-and-agents-md` | `skills/skill-authoring/folder-specific-claude-and-agents-md` |
| `$david-push-skill-to-github` | `push-skill-to-github` | `skills/skill-authoring/push-skill-to-github` |
| `$david-brain-to-docs` | `brain-to-docs` | `skills/thinking-and-docs/brain-to-docs` |
| `$david-level-up` | `level-up` | `skills/thinking-and-docs/level-up` |
| `$david-prompt-me` | `prompt-me` | `skills/thinking-and-docs/prompt-me` |
| `$david-read-all-adrs` | `read-all-adrs` | `skills/thinking-and-docs/read-all-adrs` |
| `$david-short` | `short` | `skills/thinking-and-docs/short` |
| `$david-teach` | `teach` | `skills/thinking-and-docs/teach` |

## Source Pins

- Matt Pocock skills: `391a2701dd948f94f56a39f7533f8eea9a859c87`
- David Ondrej skills: `5c99080334072075eb9e0a17837f7d24e4f3e6ae`
Loading