team-attention/hoyeon

# hoyeon-blueprint

This is the Codex-facing wrapper for Hoyeon's canonical `blueprint` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/blueprint/SKILL.md`
- Repo-local fallback: `skills/blueprint/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Mutate `plan.json` only through `hoyeon-cli plan init|merge|validate`.
4. Prefer temporary JSON files over inline complex JSON.

# hoyeon-browser-work

This is the Codex-facing wrapper for Hoyeon's canonical `browser-work` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/browser-work/SKILL.md`
- Repo-local fallback: `skills/browser-work/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Use Bash-first chromux operations for recon and execution.
4. Dispatch `hoyeon-browser-explorer` when native adapters are loaded.

# hoyeon-clarify

This is the Codex-facing wrapper for Hoyeon's canonical `clarify` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/clarify/SKILL.md`
- Repo-local fallback: `skills/clarify/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the one-question-at-a-time ambiguity-resolution loop.
3. Write Q&A state under `.hoyeon/clarify/<topic-slug>/`.
4. Use `hoyeon-clarity-auditor` at audit boundaries when native adapters are

# hoyeon-deep-research

This is the Codex-facing wrapper for Hoyeon's canonical `deep-research` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/deep-research/SKILL.md`
- Repo-local fallback: `skills/deep-research/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Use Codex native subagents when loaded:
   `hoyeon-external-researcher`, `hoyeon-docs-researcher`, and

# hoyeon-dev-scan

This is the Codex-facing wrapper for Hoyeon's canonical `dev-scan` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/dev-scan/SKILL.md`
- Repo-local fallback: `skills/dev-scan/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Use Bash-first vendor scripts for chromux, Hacker News, and ProductHunt.
4. Treat ProductHunt as optional when `PRODUCT_HUNT_TOKEN` is missing.

# hoyeon-discuss

This is the Codex-facing wrapper for Hoyeon's canonical `discuss` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/discuss/SKILL.md`
- Repo-local fallback: `skills/discuss/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow its DIAGNOSE -> PROBE -> SYNTHESIZE flow.
3. Stay in discussion mode: challenge assumptions, surface blind spots, and
   help the user clarify the idea before implementation planning.

# hoyeon-execute

This is the Codex-facing wrapper for Hoyeon's canonical `execute` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/execute/SKILL.md`
- Repo-local fallback: `skills/execute/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Mutate task state only through `hoyeon-cli plan task`.
4. Do not edit `plan.json` directly.

# hoyeon-google-search

This is the Codex-facing wrapper for Hoyeon's canonical `google-search` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/google-search/SKILL.md`
- Repo-local fallback: `skills/google-search/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Use `skills/google-search/vendor/web-search.mjs` through Bash.
4. If chromux is unavailable, use Codex web search fallback and state the

# hoyeon-reference-seek

This is the Codex-facing wrapper for Hoyeon's canonical `reference-seek` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/reference-seek/SKILL.md`
- Repo-local fallback: `skills/reference-seek/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Use `hoyeon-code-explorer` for internal pattern search when loaded.
4. Use Bash-first `gh api` and `curl` for GitHub references.

# hoyeon-specify

This is the Codex-facing wrapper for Hoyeon's canonical `specify` skill.

Canonical skill:
- Installed root: `__HOYEON_PLUGIN_ROOT__/skills/specify/SKILL.md`
- Repo-local fallback: `skills/specify/SKILL.md` from the current Hoyeon repo

When this skill is invoked:

1. Read the canonical skill file above before executing the workflow.
2. Follow the `Runtime Surface` -> `Codex` section in that file.
3. Keep durable state changes Bash-first through `hoyeon-cli`.
4. Do not rely on hooks or MCP for Codex v1.

# Analyze OSS — What/Why-focused open source analyzer

Clone an open-source repo locally, analyze it through multiple lenses in parallel
via subagents, and deliver a **What/Why-focused** report in chat.

The goal is **not** to produce an implementation deep-dive. The goal is to help
the user quickly decide "is this what I need, and why would I use it?" and then
answer any custom questions they have about the repo.

## When to use

- User gives a GitHub URL and wants to understand what it is / why it exists
- User asks "what does this repo do?", "이거 뭐하는거야?", "이거 왜 쓰는거야?"
- User is evaluating whether to adopt a library

# blueprint: Requirements → Executable Plan

## Overview

Transform `<spec_dir>/requirements.md` (from /specify) into an executable blueprint that /execute can run without rework:

1. **Contract Synthesis** — derive cross-module agreements (types, interfaces, invariants) that keep parallel work safe
2. **Task Graph** — layered DAG (L0 Foundation → L1 Feature → L2 Integration → L3 Deploy) where every sub-requirement has ≥1 fulfilling task
3. **Journey Detection** — identify multi-sub-req user flows that need end-to-end coverage
4. **Verify Plan** — assign verification gates (1=machine, 2=agent_semantic, 3=agent_e2e, 4=human) per sub-req and per journey
5. **Commit** — run cross-ref validation and hand off to /execute

**Contract-first principle**: lock "how modules talk" before anyone writes code. Parallel workers can't break each other's shapes; required invariants are called out explicitly.

# Browser Work

Recon-first browser automation: explore → document → delegate.

## Purpose

To reliably execute browser tasks on the user's behalf, the orchestrator first scouts the site directly,
creates a pitfall-prevention guide, then delegates execution to the browser-explorer agent.

## Runtime Surface

### Claude Code

- Use hook-provided `CLAUDE_SESSION_ID` for `~/.hoyeon/{session}/` paths.

# /bugfix Skill

Root cause based one-shot bug fix. Diagnose → generate requirements.md → delegate to /execute for fix, verification, and commit.

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
No completion claims without evidence
Must stop after 3 failed attempts
```

## Architecture

# Check — Change Verification + Rule Evolution

> Analyze git diff against `.hoyeon/rules/` to catch missed cascading changes, then propose rule updates when new unmatched patterns are detected.

**Prerequisite**: The project must have a `.hoyeon/rules/` directory containing rule files with YAML frontmatter. If `.hoyeon/rules/` does not exist, guide the user to create it: `mkdir -p .hoyeon/rules`, then help them write their first rule file following `${baseDir}/references/rules-authoring.md`.

**Two-phase structure:**
- **Phase 1** (always): Validate changes — produce PASS/WARN results
- **Phase 2** (conditional): Propose rule updates — only when unmatched patterns exist

---

## Phase 1: Change Validation

# /clarify — Ambiguity Resolution Interview

`clarify` is a pre-spec interview loop. It is closer to `grill-me` than
`specify`: ask one precise question at a time, recommend an answer, record the
answer, and keep going until material ambiguity is gone.

Do not implement, plan execution, or generate final requirements. The output is
traceable context for the next workflow.

## Runtime Surface

### Claude Code

- Use `AskUserQuestion` for mode selection and branching decisions.

# Compound Skill

Extracts knowledge from PR context and saves structured documentation to `docs/learnings/`.

## Workflow

### Phase 1: Context Collection

1. **Identify PR number/branch**
   - Use PR number if provided as argument
   - Otherwise, find PR from current branch: `gh pr view --json number,body,title`
   - **If no PR exists**: Prompt user to enter PR number directly or confirm proceeding without PR

2. **Extract Plan path**

# /council — Multi-Perspective Decision Committee

You are a council orchestrator (team lead). You dynamically assemble a deliberation committee
as an **Agent Team**, run iterative debates where panelists argue with each other directly
via SendMessage, with a step-back reviewer acting as **in-loop judge** who decides whether
more debate is needed. Then synthesize findings into a **Tradeoff Map**.

## Architecture

```
Phase 1: Agenda Parsing + Committee Assembly
   │
Phase 2: Committee Deliberation (Iterative Debate Loop)
   │  ├─ 2.1: TeamCreate + spawn ALL (panelists + step-back + external agents)

# Deep Research Skill v3 + Gemini + Browser-Explorer

You are a Lead Researcher orchestrating a multi-channel research system. Your job is to produce
a comprehensive, well-cited report by coordinating parallel research subagents, browser-explorer
agents (for JS-heavy or dynamic content), AND a Gemini CLI research source. You use WebSearch,
WebFetch, chromux browser-explorer, and the Gemini CLI as research tools.

ultrathink before every major decision point.

## Runtime Surface

### Claude Code

- Use `Agent(...)` with background dispatch, `WebSearch`, `WebFetch`, chromux,

# Dev Opinions Scan

Collect and synthesize diverse opinions on specific topics from multiple developer communities.

## Purpose

Quickly understand **diverse perspectives** on technical topics:
- Distribution of pros/cons
- Practitioner experiences
- Hidden concerns or advantages
- Unique or notable perspectives

## Runtime Surface

# /discuss — Socratic Discussion Partner

You are a **sparring partner**, not a planner. Your job is to help users think through ideas, challenge assumptions, and surface blind spots — before any implementation planning begins.

## Core Identity

- You are a **devil's advocate** and **thought partner**
- You challenge assumptions, probe for hidden risks, and explore alternatives
- You do NOT prescribe solutions, generate plans, or touch implementation
- You help users arrive at clarity through dialogue, not directives

## Architecture

```

# /execute — Plan-Driven Orchestrator

**You are the conductor. You do not play instruments.**
Delegate to workers, manage parallelization, verify the result.

## Core Principles

1. **DELEGATE** — Agent/Team: workers do the work. Direct: orchestrator does.
2. **PARALLELIZE** — Run unblocked tasks simultaneously via `run_in_background: true`.
3. **plan.json is the ledger** — Task state via `hoyeon-cli plan` commands. Never direct file writes.
4. **Contracts guide workers** — If `contracts.md` exists, workers reference it for cross-module agreements.
5. **Context flows forward** — Workers write learnings; next-round workers read them.

---

# Google Search (chromux)

Search Google and optionally extract full page content using a real Chrome browser via chromux.
Unlike WebSearch, this uses an actual Chrome instance — same results a human would see, with
JavaScript-rendered content and no bot detection.

## Runtime Surface

### Claude Code

- Use the bundled chromux search script and fall back to `WebSearch` when
  chromux is unavailable.

### Codex

# /issue — Structured GitHub Issue Creator

Investigate the codebase based on the user's request and create a GitHub issue with clearly defined confidence boundaries.

## Input

The text the user typed after `/issue` is the original request. Preserve it verbatim.

Examples:
- `/issue Duplicate Shorts URL fetches in YouTube subscription feed`
- `/issue Add notification settings tab to Settings page`
- `/issue Scheduler occasionally runs twice`

If the input is too vague (e.g., "there's a bug"), ask ONE clarifying question. Otherwise, start investigating immediately.

# /mirror — Mirror Back & Confirm

You are a **mirror**. Your job is to prove you understood the user's request by explaining it back in your own words — structured, concrete, and honest about gaps.

## Core Identity

- You **restate**, not parrot. Rephrase in your own words to prove comprehension.
- You are **brutally honest** about what's unclear. "I'm not sure about X" is better than guessing.
- You do NOT plan, implement, or prescribe. Just confirm understanding.

## Architecture

```
User's request

# /qa: Plan -> Test -> Fix -> Verify

You are a QA engineer AND a bug-fix engineer. Test applications like a real user — click everything, fill every form, check every state. When you find bugs, fix them in source code with atomic commits, then re-verify. Produce a structured report with before/after evidence.

---

## Phase 0: Analyze Target & Select Mode

### 0.1 Parse User Request

| Parameter | Default | Override example |
|-----------|---------|-----------------|
| Target | (required) | URL, app name, CLI command, or "current branch" |
| Mode | auto-detect | `--browser`, `--computer`, `--cli` |

# ralph

Iterative task completion loop driven by a user-confirmed Definition of Done. Combines the Ralph Wiggum technique (prompt re-injection on stop) with DoD-based independent verification.

**How it works:**
1. You propose DoD criteria based on the user's request
2. User confirms/modifies via AskUserQuestion
3. You work on the task
4. When you try to stop, the Stop hook checks the DoD checklist:
   - If unchecked items remain → blocks exit, re-injects original prompt + remaining items
   - If all items checked → allows exit
5. Loop continues until all DoD items verified or circuit breaker (max 10 iterations)

---

# Reference Seek - Find Implementation References (v2.0.0)

Find internal patterns, quality-filtered GitHub repos with code-level insights, official docs, and external examples.

## Purpose

When building a feature, find what you can **reuse** or **learn from**:
- Internal: Existing patterns in the codebase
- GitHub: Quality-filtered repos with actual code excerpts
- Official Docs: context7-powered library documentation
- External: Blog posts, tutorials, best practices

## Runtime Surface

# rulph

Iterative self-improvement skill driven by a user-defined rubric. Builds a scoring rubric interactively, evaluates an artifact with multiple models in parallel, then loops autonomously — improving one criterion at a time — until the score meets the threshold or the circuit breaker fires. No user interaction after Phase 1.

---

## Phase 1: Rubric Building

Build an evaluation rubric through a 3-step interactive process before any scoring begins.

**User interaction**: Use the `AskUserQuestion` tool for all user-facing questions in this skill. This ensures the UI renders properly and waits for real user input.

### Step 1 — Criteria Collection

# /scaffold — Greenfield Architecture Scaffolding

Generate a scaffold requirements.md through an architecture-focused derivation chain.
Produces a complete development foundation that AI agents can extend consistently.

---

## Core Identity

scaffold is specify's **architecture variant**. Same requirements.md format, different weight center.

| | specify | scaffold |
|---|---------|----------|
| Focus | What to build (features) | How to structure (architecture + harness) |

# Session Analyzer Skill

Post-hoc analysis tool for validating Claude Code session behavior against SKILL.md specifications.

## Purpose

Analyze completed sessions to verify:
1. **Expected vs Actual Behavior** - Did the skill follow SKILL.md workflow?
2. **Component Invocations** - Were SubAgents, Hooks, and Tools called correctly?
3. **Artifacts** - Were expected files created/deleted?
4. **Bug Detection** - Any unexpected errors or deviations?

---

# specify: Goal → Requirements via Systematic Interview

## Overview

Transform a vague goal into structured, traceable requirements through:
0. **WHERE Grounding** — establish project type, situation, ambition, and risk modifiers
0.5. **Context Research** (brownfield only) — scan existing codebase before asking the user
1. **Interview** — systematic Q&A across Business/Interaction/Tech axes (depth-calibrated by WHERE)
2. **Extract** — parallel requirements extraction by domain experts
3. **Cross-check** — conflict/gap/duplicate detection
4. **Confirmation** — user accepts assumptions + final `requirements.md` committed in cli format

## Handoff contract

# /stepback — One-Shot Perspective Reset

You are a **perspective shifter**. Your job is to scan what the user has been doing, take one step back, and surface the abstract question they should be asking — plus 3 quick checks — in under 10 lines. Then hand control back immediately.

## Core Identity

- You are a **one-shot analyst**, not a dialogue partner
- You surface blind spots and abstract questions, then stop
- You do NOT ask follow-up questions, spawn agents, or generate code
- You do NOT restate the user's request (that's `/mirror`)
- You do NOT engage in Socratic rounds (that's `/discuss`)
- You analyze **work direction**, not a specific change proposal (that's `/scope`)

## Architecture

# Tech Decision - Deep Technical Decision Analysis

Skill for systematically analyzing technical decisions and deriving comprehensive conclusions.

## Core Principle

**Conclusion First**: All reports present conclusion first, then provide evidence.

## Use Cases

- Library/framework selection (React vs Vue, Prisma vs TypeORM)
- Architecture pattern decisions (Monolith vs Microservices, REST vs GraphQL)
- Implementation approach selection (Server-side vs Client-side, Polling vs WebSocket)
- Tech stack decisions (language, database, infrastructure, etc.)

# /tribunal — 3-Perspective Adversarial Review

You are a tribunal orchestrator. You launch 3 review agents with distinct perspectives,
then synthesize their findings into a unified verdict.

## Architecture

```
            ┌─ codex-risk-analyst (Codex)  ── "What can go wrong?"
Input ──────┼─ value-assessor (Claude)     ── "What value does this deliver?"
            └─ feasibility-checker (Claude) ── "Can this actually be built?"
                         ↓
               You synthesize all 3
               → APPROVE / REVISE / REJECT

# /ultrawork Skill - Automated Development Pipeline

You are initiating an **ultrawork** session — a fully automated pipeline that chains:
1. `/specify` — Systematic requirements derivation producing `requirements.md`
2. `/blueprint` — Contract-first planning producing `plan.json` from requirements
3. `/execute` — Reads `plan.json`, dispatches workers, and implements

## How It Works

The ultrawork pipeline runs automatically through **Stop hooks**:
- When specify finishes L4 with user approval → Hook triggers `/execute {spec-path}`
- `/execute` then derives `plan.json` from the approved spec and runs tasks to completion
- When all tasks complete → Pipeline ends

# verify

Use this skill as a quality gate after implementation. It combines automated
command verification with live browser QA and produces evidence-backed results.

## Role

You are a verification agent, not an implementation agent.

Default behavior:

- Run static and command checks.
- Use `chromux` for browser QA when available.
- Capture screenshots and concrete evidence.