From 9b88e29630172e2fe7c3c67f464bd30bbf56b6dc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Jun 2026 11:50:19 +0000 Subject: [PATCH 1/6] docs+validate: add npx skills install path and skill authoring conventions - validate-plugins.sh now parses every skills/*/SKILL.md frontmatter and fails on invalid YAML, missing name/description, name/directory mismatch, or descriptions over 1024 chars (catches the unquoted-colon bug that hides skills from npx skills discovery) - README: npx skills quick start + skill style section - AGENTS.md: Skill Authoring Conventions (mattpocock/skills style), npx skills distribution channel https://claude.ai/code/session_01YPKG1K27VWQWEMcS9NJK1a --- AGENTS.md | 34 +++++++++++++++++++++++------- README.md | 30 +++++++++++++++++++++++++++ scripts/validate-plugins.sh | 41 +++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b75fd7..82e163c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,9 +27,9 @@ plugin-name/ │ └── helper.md ├── skills/ # Agent Skills — both tools (SKILL.md format is shared) │ └── my-skill/ -│ ├── SKILL.md -│ ├── PRINCIPLES.md -│ └── EXAMPLES.md +│ ├── SKILL.md # ≤100 lines; see Skill Authoring Conventions +│ ├── reference.md # overflow detail, linked one level deep +│ └── templates/ ├── hooks/ # Event hooks (Claude Code format) │ └── hooks.json ├── .mcp.json # MCP servers (Claude Code format) @@ -131,8 +131,26 @@ codex plugin marketplace upgrade devstefancho-claude-plugins **Skills** (`skills//SKILL.md`) - Required `SKILL.md` with metadata frontmatter and instructions. -- Optional supporting files (`PRINCIPLES.md`, `EXAMPLES.md`, `scripts/`, `references/`). -- Auto-loaded by both tools when relevant context is detected. +- Optional supporting files (`reference.md`, `templates/`, `scripts/`, `references/`). +- Auto-loaded by both tools when relevant context is detected, and installable standalone via `npx skills add devstefancho/claude-plugins`. +- Must follow the Skill Authoring Conventions below. + +### Skill Authoring Conventions + +Skills follow the style of [mattpocock/skills](https://github.com/mattpocock/skills). When creating or editing a skill: + +**Frontmatter** +- `name` (required): kebab-case, must match the skill directory name. Never rename casually — it is the installed-skill identity. +- `description` (required): single line, third person, two-sentence pattern — first what the skill does, then `Use when [explicit triggers]` listing literal phrases users say (keep Korean trigger phrases like 스펙 생성, 팀 만들어줘). Max 1024 chars. +- **The description must be valid YAML.** A bare colon inside an unquoted value breaks parsing and silently hides the skill from `npx skills` and frontmatter-driven discovery — wrap the value in double quotes if it contains `:`. `scripts/validate-plugins.sh` enforces this. +- Claude-specific fields (`allowed-tools`, `context`, `agent`, `model`, `effort`, `user-invocable`) are allowed; other agents ignore them. +- Internal-only skills add `metadata.internal: true` so `npx skills` hides them from discovery. + +**Body** +- `# Title` then short `##` sections. Terse, imperative, opinionated. Bold the hard rules. +- Use numbered phases for workflows and `- [ ]` checklists as gates between phases. +- Add an Anti-patterns section with WRONG/RIGHT contrast where the skill has known failure modes. +- Keep `SKILL.md` under ~100 lines. Move overflow into sibling `.md` files in the same skill directory, linked one level deep (`See [reference.md](reference.md)`). Never delete behavior-critical detail — relocate it. **Subagents** (`agents/*.md`) - One Markdown file per subagent. @@ -169,6 +187,7 @@ What it verifies: - `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json` list the same plugin names. - Each Codex marketplace entry uses the correct schema: `source.source = "local"`, `source.path` matches the Claude side, `policy.installation` ∈ {`AVAILABLE`, `NOT_AVAILABLE`, `INSTALLED_BY_DEFAULT`}, `policy.authentication` ∈ {`ON_INSTALL`, `ON_USE`}, and `category` is non-empty. - Every `AVAILABLE` Codex plugin actually has at least one Codex-loadable component (`skills/`, `agents/`, `.app.json`, or `codex.config.toml.snippet`). +- Every `skills/*/SKILL.md` has parseable YAML frontmatter with non-empty `name` (matching its directory) and `description` (≤1024 chars). This catches the unquoted-colon bug that hides skills from `npx skills` discovery (requires `python3`; YAML parse check additionally requires PyYAML). Run this before pushing any change that touches manifests or the marketplace catalog. A failing run almost always means one of the paired files was edited without the other. @@ -195,8 +214,9 @@ Recommended workflow when adding or removing a marketplace entry: Plugins are shared via: 1. **Git Repository** — both tools support GitHub shorthand (`/`). -2. **Local Development** — point the tool's marketplace at a local path. -3. **Team Configuration** — use `.claude/settings.json` for Claude Code; Codex records configured marketplaces in `~/.codex/config.toml` after `codex plugin marketplace add`. +2. **`npx skills`** — the [skills CLI](https://github.com/vercel-labs/skills) discovers every skill in this repo through `.claude-plugin/marketplace.json` and installs them into 70+ agents: `npx skills add devstefancho/claude-plugins`. Skill-only distribution — commands, hooks, and MCP servers still require a plugin install. +3. **Local Development** — point the tool's marketplace at a local path. +4. **Team Configuration** — use `.claude/settings.json` for Claude Code; Codex records configured marketplaces in `~/.codex/config.toml` after `codex plugin marketplace add`. ## See Also diff --git a/README.md b/README.md index d9ef73e..27d9355 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,26 @@ A collection of reusable plugins for AI coding agents — slash commands, agent ## Quick Start +### Any agent — `npx skills` (recommended) + +Skills in this repo install into 70+ agents (Claude Code, Codex, Cursor, Copilot, ...) via the [skills CLI](https://github.com/vercel-labs/skills): + +```bash +# Interactive: pick skills + target agents +npx skills add devstefancho/claude-plugins + +# List available skills without installing +npx skills add devstefancho/claude-plugins --list + +# Install one skill non-interactively +npx skills add devstefancho/claude-plugins --skill writing-specs -a claude-code -y + +# Install everything to all detected agents +npx skills add devstefancho/claude-plugins --all +``` + +`npx skills` installs the skill content only. To get slash commands, hooks, and MCP servers too, install the full plugin through Claude Code or Codex below. + ### Claude Code ```bash @@ -60,6 +80,16 @@ codex plugin marketplace add devstefancho/claude-plugins | [session-resume-plugin](./session-resume-plugin) | Yes | Yes | Resume work from a previous Claude Code or Codex CLI session by reading the last N turns from its JSONL transcript | | [stop-notification-plugin](./stop-notification-plugin) | Yes | No | Claude Code hook-based macOS TTS notification when Claude stops or needs attention | +## Skill Style + +Every skill follows the same conventions (inspired by [mattpocock/skills](https://github.com/mattpocock/skills)): + +- Frontmatter `description` is two sentences: what it does, then `Use when [explicit triggers]`. +- `SKILL.md` stays under ~100 lines — terse, imperative, with phase workflows and checklist gates. +- Overflow detail lives in sibling files (`reference.md`, `templates/`, `scripts/`), linked one level deep. + +See the Skill Authoring Conventions section in [`AGENTS.md`](./AGENTS.md) before adding or editing a skill. + ## Plugin Structure Each plugin ships parallel manifests. Plugins marked as Codex-compatible include Codex-loadable components such as skills: diff --git a/scripts/validate-plugins.sh b/scripts/validate-plugins.sh index cee4822..cfa3f96 100755 --- a/scripts/validate-plugins.sh +++ b/scripts/validate-plugins.sh @@ -46,6 +46,47 @@ for claude_manifest in */.claude-plugin/plugin.json; do echo "FAIL [$plugin_dir]: .codex-plugin/plugin.json must declare skills: \"./skills/\"" fail=1 fi + + # Every SKILL.md must have parseable YAML frontmatter with name + description. + # An unquoted colon in `description:` silently hides the skill from + # `npx skills` and other frontmatter-driven discovery. + for skill_md in "$plugin_dir"/skills/*/SKILL.md; do + [[ -f "$skill_md" ]] || continue + if command -v python3 >/dev/null 2>&1; then + if ! err=$(python3 - "$skill_md" <<'PY' 2>&1 +import sys +text = open(sys.argv[1], encoding="utf-8").read() +if not text.startswith("---\n"): + sys.exit("missing frontmatter delimiter") +body = text[4:] +end = body.find("\n---") +if end == -1: + sys.exit("unterminated frontmatter") +try: + import yaml + data = yaml.safe_load(body[:end]) +except ModuleNotFoundError: + sys.exit(0) # PyYAML unavailable; structural checks above still ran +except Exception as exc: + sys.exit(f"invalid YAML: {exc}") +if not isinstance(data, dict): + sys.exit("frontmatter is not a mapping") +for field in ("name", "description"): + value = data.get(field) + if not isinstance(value, str) or not value.strip(): + sys.exit(f"missing or empty '{field}'") +if len(data["description"]) > 1024: + sys.exit("description exceeds 1024 chars") +expected = sys.argv[1].split("/")[-2] +if data["name"] != expected: + sys.exit(f"name '{data['name']}' does not match directory '{expected}'") +PY + ); then + echo "FAIL [$skill_md]: $err" + fail=1 + fi + fi + done fi done From 83aca9de11746ffd4a01bbc189f86c1c73e6a7b7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Jun 2026 11:51:21 +0000 Subject: [PATCH 2/6] skills: restyle five short skills to mattpocock/skills conventions - create-team 2.1.0, session-resume 1.1.0, split-work 1.1.0, test-commit-push-pr-clean 1.4.0, hermes 1.1.0 - two-sentence 'Use when' descriptions with all triggers preserved - fix unquoted-colon YAML bug that hid test-commit-push-pr-clean from npx skills discovery - mark hermes-runtime metadata.internal: true to hide it from discovery https://claude.ai/code/session_01YPKG1K27VWQWEMcS9NJK1a --- agent-team-plugin/.claude-plugin/plugin.json | 2 +- agent-team-plugin/.codex-plugin/plugin.json | 2 +- agent-team-plugin/skills/create-team/SKILL.md | 75 +++++++--------- .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- .../skills/hermes-runtime/SKILL.md | 56 +++++++----- .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- .../skills/session-resume/SKILL.md | 78 +++++++---------- split-work-plugin/.claude-plugin/plugin.json | 2 +- split-work-plugin/.codex-plugin/plugin.json | 2 +- split-work-plugin/skills/split-work/SKILL.md | 87 +++++++++++-------- .../.claude-plugin/plugin.json | 2 +- .../.codex-plugin/plugin.json | 2 +- .../skills/test-commit-push-pr-clean/SKILL.md | 54 ++++++------ 15 files changed, 179 insertions(+), 191 deletions(-) diff --git a/agent-team-plugin/.claude-plugin/plugin.json b/agent-team-plugin/.claude-plugin/plugin.json index 968c4fa..8576683 100644 --- a/agent-team-plugin/.claude-plugin/plugin.json +++ b/agent-team-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-team-plugin", "description": "Agent team management - create, expand, and cleanup teams for worktree sessions", - "version": "2.0.5", + "version": "2.1.0", "author": { "name": "Stefan Cho" } diff --git a/agent-team-plugin/.codex-plugin/plugin.json b/agent-team-plugin/.codex-plugin/plugin.json index 5f1e898..f478b59 100644 --- a/agent-team-plugin/.codex-plugin/plugin.json +++ b/agent-team-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-team-plugin", "description": "Agent team management - create, expand, and cleanup teams for worktree sessions", - "version": "2.0.5", + "version": "2.1.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/agent-team-plugin/skills/create-team/SKILL.md b/agent-team-plugin/skills/create-team/SKILL.md index 86ccc26..29f9828 100644 --- a/agent-team-plugin/skills/create-team/SKILL.md +++ b/agent-team-plugin/skills/create-team/SKILL.md @@ -1,74 +1,57 @@ --- name: create-team -description: Create an agent team with planner and implementer teammates for spec-driven development. Use when user says "create team", "팀 생성", "팀 만들어줘", "agent team", or wants to set up a planner+implementer workflow in a worktree session. +description: Creates a planner + implementer agent team for the current worktree session. Use when user says "create team", "팀 생성", "팀 만들어줘", "agent team", or wants a planner+implementer spec-driven workflow in a worktree session. effort: medium allowed-tools: Bash, Agent, SendMessage, TeamCreate, TaskCreate, TaskList, TaskUpdate, Read, AskUserQuestion --- # Create Team -Creates a planner + implementer agent team for the current worktree session. +Spin up a planner + implementer agent team for the current worktree session. -## Workflow +## Phase 1 — Derive the team name -### Step 1: Determine team name +Run `git branch --show-current`, then convert to kebab-case: -Run `git branch --show-current` to get the current branch name. Convert to kebab-case team name: -- Remove `worktree-` prefix if present +- Strip a `worktree-` prefix - Replace `+` with `-` - Example: `worktree-feat+electron-app` → `feat-electron-app` -### Step 2: Create the team +## Phase 2 — Create the team -Call `TeamCreate` with: -- `team_name`: the derived team name -- `description`: "Planner + Implementer team" +Call `TeamCreate` with `team_name` = derived name, `description` = "Planner + Implementer team". -### Step 3: Spawn teammates (parallel) +## Phase 3 — Spawn teammates in parallel -Spawn both teammates **in parallel** using the Agent tool in a single message with two tool calls: +**One message, two Agent tool calls.** Both with the team name and `run_in_background: true`. -**Planner:** -- `team_name`: the team name -- `name`: "planner" -- `description`: "Planner - brainstorm and spec writing" -- `prompt`: Read the full content of [templates/planner-prompt.md](templates/planner-prompt.md) and pass it as the prompt -- `run_in_background`: true +- **planner** — description "Planner - brainstorm and spec writing"; prompt = full content of [templates/planner-prompt.md](templates/planner-prompt.md) +- **implementer** — description "Implementer - code and test writing"; prompt = full content of [templates/implementer-prompt.md](templates/implementer-prompt.md) -**Implementer:** -- `team_name`: the team name -- `name`: "implementer" -- `description`: "Implementer - code and test writing" -- `prompt`: Read the full content of [templates/implementer-prompt.md](templates/implementer-prompt.md) and pass it as the prompt -- `run_in_background`: true +## Phase 4 — Loop setup -### Step 4: Loop setup +Send via SendMessage: -Send loop configuration via SendMessage: -- To "planner": If `/writing-specs` skill is available, "Run `/loop 10m /writing-specs update spec` to periodically check and update specs." Otherwise skip this loop setup. -- To "implementer": "After completing assigned work, check TaskList for new tasks. You can run `/loop 10m check TaskList for unassigned tasks and report to team-lead` to automate this." +- To **planner** — only if the `/writing-specs` skill is available: "Run `/loop 10m /writing-specs update spec` to periodically check and update specs." Otherwise skip. +- To **implementer**: "After completing assigned work, check TaskList for new tasks. You can run `/loop 10m check TaskList for unassigned tasks and report to team-lead` to automate this." -### Step 5: Display work guide +## Phase 5 — Display the work guide -Read [templates/work-guide.md](templates/work-guide.md) and display the content to the user. -Teammate colors are auto-assigned from a hardcoded palette and cannot be configured programmatically. +Read [templates/work-guide.md](templates/work-guide.md) and display it to the user. -## Fallback +## Fallback — teammate spawning fails -If teammate spawning via the Agent tool fails with `team_name` or another internal error in the current session (known issue anthropics/claude-code#40270): -1. Inform the user that team creation succeeded but teammate spawning failed in the current execution context -2. Suggest spawning teammates manually: - - Open separate terminal windows - - Run `claude` in each with the planner/implementer prompts - - Use SendMessage for coordination -3. Do not claim the Agent tool is globally unavailable unless the session explicitly shows that tool is missing +If the Agent tool fails with a `team_name` or other internal error in the current session (known issue anthropics/claude-code#40270): -## Notes +1. Tell the user team creation succeeded but teammate spawning failed in this execution context. +2. Suggest manual spawning: open separate terminals, run `claude` in each with the planner/implementer prompts, coordinate via SendMessage. -- Teammates are full Claude Code sessions, not subagents -- Both teammates can use all tools including Write, Edit, Bash -- Both can run skills like `/writing-specs`, `/loop` -- `/loop` is session-scoped and expires after 7 days -- Teammate colors are auto-assigned from hardcoded palette (red, blue, green, yellow...) — not configurable -- All communication flows through team-lead (planner <-> implementer direct messaging disabled by prompt rules) +**Never claim the Agent tool is globally unavailable** unless the session explicitly shows the tool missing. + +## Facts + +- Teammates are full Claude Code sessions, not subagents — all tools (Write, Edit, Bash) and skills (`/writing-specs`, `/loop`) available. +- `/loop` is session-scoped and expires after 7 days. +- Teammate colors are auto-assigned from a hardcoded palette — not configurable. +- All communication flows through team-lead; planner ↔ implementer direct messaging is disabled by prompt rules. - Teammate model defaults to standard Opus. diff --git a/hermes-gateway-plugin/.claude-plugin/plugin.json b/hermes-gateway-plugin/.claude-plugin/plugin.json index 33ae4f3..fcc9af3 100644 --- a/hermes-gateway-plugin/.claude-plugin/plugin.json +++ b/hermes-gateway-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hermes", "description": "Interact with Hermes Agent via local or SSH-tunneled connection", - "version": "1.0.1", + "version": "1.1.0", "author": { "name": "Stefan Cho" } diff --git a/hermes-gateway-plugin/.codex-plugin/plugin.json b/hermes-gateway-plugin/.codex-plugin/plugin.json index e3fa5cd..ae52e31 100644 --- a/hermes-gateway-plugin/.codex-plugin/plugin.json +++ b/hermes-gateway-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hermes", "description": "Interact with Hermes Agent via local or SSH-tunneled connection", - "version": "1.0.1", + "version": "1.1.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/hermes-gateway-plugin/skills/hermes-runtime/SKILL.md b/hermes-gateway-plugin/skills/hermes-runtime/SKILL.md index b0b0f4e..42f29c2 100644 --- a/hermes-gateway-plugin/skills/hermes-runtime/SKILL.md +++ b/hermes-gateway-plugin/skills/hermes-runtime/SKILL.md @@ -1,32 +1,40 @@ --- name: hermes-runtime -description: Internal helper contract for calling the hermes-companion runtime from Claude Code +description: Internal contract for calling the hermes-companion runtime helper. Use only from hermes-gateway plugin commands and subagents — never user-invocable, never auto-loaded for user requests. user-invocable: false +metadata: + internal: true --- # Hermes Runtime -Use this skill only inside hermes-gateway plugin commands and subagents. - -Primary helper: -- `node "${CLAUDE_PLUGIN_ROOT}/scripts/hermes-companion.mjs" ` - -Available subcommands: -- `setup [--json]` - Check connectivity (auto-detects local vs SSH mode) -- `chat [--stream] [--system ] [--json]` - Send message to Hermes -- `run [--background] [--json]` - Start async run with event streaming -- `status [job-id] [--json]` - Check connection/job status -- `jobs [list|delete ] [--json]` - Manage cron jobs -- `tunnel [start|stop|status]` - Manage SSH tunnel directly - -Execution rules: -- Prefer the helper over hand-rolled SSH, curl, or HTTP commands -- Return stdout verbatim without paraphrasing or summarizing -- Do not inspect files, monitor progress, or do follow-up work -- If the helper reports connectivity failure, suggest running `/hermes:setup` - -Connection modes: -- **auto** (default): tries localhost:8642 first, then SSH tunnel -- **local**: direct connection to localhost:8642 -- **ssh**: SSH tunnel to remote host (default: `arch`) +Internal contract. **Only invoke from hermes-gateway plugin commands and subagents.** + +## Helper + +```bash +node "${CLAUDE_PLUGIN_ROOT}/scripts/hermes-companion.mjs" +``` + +Subcommands: + +- `setup [--json]` — check connectivity (auto-detects local vs SSH mode) +- `chat [--stream] [--system ] [--json]` — send message to Hermes +- `run [--background] [--json]` — start async run with event streaming +- `status [job-id] [--json]` — check connection/job status +- `jobs [list|delete ] [--json]` — manage cron jobs +- `tunnel [start|stop|status]` — manage SSH tunnel directly + +## Rules + +- **Always use the helper.** Never hand-roll SSH, curl, or HTTP commands. +- Return stdout verbatim — no paraphrasing, no summarizing. +- Do not inspect files, monitor progress, or do follow-up work. +- On connectivity failure, suggest running `/hermes:setup`. + +## Connection modes + +- **auto** (default) — tries localhost:8642 first, then SSH tunnel +- **local** — direct connection to localhost:8642 +- **ssh** — SSH tunnel to remote host (default `arch`) - Config file: `~/.claude/hermes/config.json` diff --git a/session-resume-plugin/.claude-plugin/plugin.json b/session-resume-plugin/.claude-plugin/plugin.json index 07ca4b6..e8e0955 100644 --- a/session-resume-plugin/.claude-plugin/plugin.json +++ b/session-resume-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "session-resume-plugin", "description": "Resume work from a previous Claude Code or Codex CLI session by reading the last N turns from its JSONL transcript", - "version": "1.0.0", + "version": "1.1.0", "author": { "name": "Stefan Cho" } diff --git a/session-resume-plugin/.codex-plugin/plugin.json b/session-resume-plugin/.codex-plugin/plugin.json index f29b188..5a7e52c 100644 --- a/session-resume-plugin/.codex-plugin/plugin.json +++ b/session-resume-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "session-resume-plugin", "description": "Resume work from a previous Claude Code or Codex CLI session by reading the last N turns from its JSONL transcript", - "version": "1.0.0", + "version": "1.1.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/session-resume-plugin/skills/session-resume/SKILL.md b/session-resume-plugin/skills/session-resume/SKILL.md index b91cc0c..d55d0aa 100644 --- a/session-resume-plugin/skills/session-resume/SKILL.md +++ b/session-resume-plugin/skills/session-resume/SKILL.md @@ -1,78 +1,60 @@ --- name: session-resume -description: Use when the user wants to resume work from a previous Claude Code or Codex CLI session — phrases like "resume", "이어가자", "이전 세션 내용 보여줘", "what was I working on", or when the user provides a session UUID. Locates the session's JSONL transcript on disk and prints the last N turns plus metadata so the agent can pick up where the previous session left off. +description: Locates a previous Claude Code or Codex CLI session's JSONL transcript and prints the last N turns plus metadata so work can continue. Use when the user says "resume", "이어가자", "이전 세션 내용 보여줘", "what was I working on", or provides a session UUID. allowed-tools: Bash, Read --- # Session Resume -Locate a previous Claude Code or Codex CLI session's JSONL transcript and surface the last N turns plus metadata (tool, branch, cwd, last-activity timestamp) so you can continue the work intelligently. - -## When to Use - -- User asks to continue/resume a previous session. -- User provides a session UUID like `019e1048-8ab2-7600-a736-1dfc5db707aa`. -- User asks "what was I working on?" or similar context-recovery questions. +Surface a previous session's last N turns plus metadata (tool, branch, cwd, last-activity timestamp), then continue the work intelligently. ## Inputs -- `$1` (optional): session UUID. If omitted, pick the most recent session in the current `cwd` (Claude Code) or globally most recent (Codex), and present the user with a short list if there is ambiguity. -- `-n N` (optional): how many of the last messages to print. Default 10. - -## Storage Layouts - -**Claude Code:** -- Path: `~/.claude/projects//.jsonl` -- `` is the absolute project path with `/` replaced by `-` (e.g. `/home/user/foo` → `-home-user-foo`). -- Filename is the session UUID. -- Each line is one event: `{type, message, timestamp, cwd, gitBranch, sessionId, uuid, parentUuid, ...}`. `type` is typically `user`, `assistant`, `summary`, or tool-related. - -**Codex CLI:** -- Path: `~/.codex/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDTHH-MM-SS-.jsonl` -- Filename embeds the session UUID at the end. -- Each line carries `payload.role` and `payload.content`; first line is a session header. -- Schema may evolve — fall back to printing raw lines if jq cannot parse expected fields. - -## Workflow - -### Step 1 — Run the helper +- `$1` (optional) — session UUID. If omitted, pick the most recent session in the current cwd (Claude Code) or globally most recent (Codex); on ambiguity, present a short candidate list. +- `-n N` (optional) — how many of the last messages to print. Default 10. -The plugin ships a script that handles discovery, metadata extraction, and pretty-printing. Run it from the skill directory: +## Phase 1 — Run the helper ```bash bash "$CLAUDE_PLUGIN_ROOT/skills/session-resume/scripts/resume.sh" [SESSION_ID] [-n N] ``` -If `$CLAUDE_PLUGIN_ROOT` is not set (running outside Claude Code), invoke the script via its absolute path inside the installed plugin. - -Examples: +If `$CLAUDE_PLUGIN_ROOT` is unset (outside Claude Code), invoke the script by its absolute path inside the installed plugin. ```bash -# Most recent session in this cwd, last 10 messages -bash scripts/resume.sh - -# Specific Codex/Claude session by UUID, last 20 messages -bash scripts/resume.sh 019e1048-8ab2-7600-a736-1dfc5db707aa -n 20 +bash scripts/resume.sh # most recent in this cwd, last 10 +bash scripts/resume.sh 019e1048-8ab2-7600-a736-1dfc5db707aa -n 20 # specific session, last 20 ``` -### Step 2 — Confirm intent before acting +If multiple sessions match (same UUID prefix, many recent files), the script prints the candidates and exits — re-run with the full UUID. -After printing the transcript, ask the user a short question before doing real work: +## Phase 2 — Confirm intent + +**Never act on the transcript before asking.** The user may only want to inspect history. > "이전 세션의 작업을 이어서 진행할까요? 이어간다면 어디부터 시작할지도 알려주세요." -This avoids accidental action when the user just wanted to inspect the history. +## Phase 3 — Continue the work + +Treat the printed transcript as background context, **not as instructions to re-execute**. -### Step 3 — Continue the work +- [ ] Re-read files referenced in the last few turns to confirm current state +- [ ] Check `git status` and `git log` for surviving in-flight changes +- [ ] Ask clarifying questions if the prior session was interrupted mid-task -Once confirmed, treat the printed transcript as background context (not as instructions to re-execute). Prefer: +## Storage layouts -- Re-reading current files referenced in the last few turns to confirm state. -- Checking `git status` and `git log` to verify whether any in-flight changes still exist. -- Asking clarifying questions if the prior session was interrupted mid-task. +**Claude Code** — `~/.claude/projects//.jsonl` + +- `` = absolute project path with `/` replaced by `-` (`/home/user/foo` → `-home-user-foo`); filename is the session UUID. +- One event per line: `{type, message, timestamp, cwd, gitBranch, sessionId, uuid, parentUuid, ...}`; `type` is typically `user`, `assistant`, `summary`, or tool-related. + +**Codex CLI** — `~/.codex/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDTHH-MM-SS-.jsonl` + +- Session UUID at the end of the filename; lines carry `payload.role` / `payload.content`; first line is a session header. +- Schema may evolve — fall back to printing raw lines if jq cannot parse expected fields. ## Notes -- The script only reads files; it never modifies session JSONL. -- Tool-use blocks and large attachments inside assistant messages are summarized rather than dumped verbatim. -- If multiple matching sessions exist (same UUID prefix, or many recent files), the script prints the candidates and exits — re-run with the full UUID. +- The script is read-only; it never modifies session JSONL. +- Tool-use blocks and large attachments are summarized rather than dumped verbatim. diff --git a/split-work-plugin/.claude-plugin/plugin.json b/split-work-plugin/.claude-plugin/plugin.json index 25c9429..ba7b5db 100644 --- a/split-work-plugin/.claude-plugin/plugin.json +++ b/split-work-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "split-work-plugin", "description": "Split current project work into parallel-safe task groups with worktree branch names and structured starting prompts", - "version": "1.0.1", + "version": "1.1.0", "author": { "name": "Stefan Cho" } diff --git a/split-work-plugin/.codex-plugin/plugin.json b/split-work-plugin/.codex-plugin/plugin.json index c3c134d..f54346b 100644 --- a/split-work-plugin/.codex-plugin/plugin.json +++ b/split-work-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "split-work-plugin", "description": "Split current project work into parallel-safe task groups with worktree branch names and structured starting prompts", - "version": "1.0.1", + "version": "1.1.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/split-work-plugin/skills/split-work/SKILL.md b/split-work-plugin/skills/split-work/SKILL.md index fdd9f6a..fc9fd68 100644 --- a/split-work-plugin/skills/split-work/SKILL.md +++ b/split-work-plugin/skills/split-work/SKILL.md @@ -1,6 +1,6 @@ --- name: split-work -description: "Split current project work into parallel-safe task groups with worktree branch names and structured starting prompts. Manual trigger via /split-work." +description: Splits current project work into parallel-safe task groups with worktree branch names and structured starting prompts. Use only on manual /split-work invocation — no automatic trigger. model: opus context: fork agent: work-status @@ -9,49 +9,66 @@ allowed-tools: Read, Glob, Grep, Bash # Split Work -시니어 개발자가 주니어들에게 업무를 분담하듯, 현재 프로젝트의 작업을 충돌 없는 병렬 묶음으로 쪼개고 각 묶음을 별도 worktree 에서 실행할 수 있도록 CLI 명령 + 시작 프롬프트를 생성한다. - -## 실행 절차 - -1. **현황 수집** — `tasks/`, `specs/`, `DEPENDENCIES.md`, `git worktree list`, 최근 커밋을 읽는다. `scripts/task-status.ts` 같은 상태 스크립트가 있으면 먼저 실행. -2. **병렬성 판단** — 각 후보의 `depends_on` 충족 + 파일/패턴 충돌 여부를 확인해 그룹화한다. 같은 그룹 안의 task 는 동시에 worktree 를 열어도 안전해야 한다. -3. **브랜치명 추천** — `git log` 로 기존 컨벤션 확인 후 `worktree-task-{번호}` 또는 `worktree-task-{범위}x` 로 제안. -4. **프롬프트 생성** — `templates/prompt.xml` 을 읽어 각 task 에 채운다. -5. **파일 저장** — `templates/output.md` 포맷대로 채운 전문을 아래 경로에 저장한다: - ``` - ~/.claude/split-work/{project-slug}/{YYYY-MM-DD-HHmm}.md - ``` - - `{project-slug}` 결정 (worktree 안에서도 main repo 기준): - ```bash - # --path-format=absolute 로 워크트리에서도 main repo 의 .git 절대 경로를 얻는다. - git_common_dir="$(git rev-parse --path-format=absolute --git-common-dir)" - main_repo="$(dirname "$git_common_dir")" - slug="$(basename "$(dirname "$main_repo")")-$(basename "$main_repo")" - # 예: ~/works/runner/web → runner-web - ``` - basename 만 쓰면 `web` 같은 generic 이름이 다른 repo 와 충돌하므로 부모 한 단계 결합. - `--path-format=absolute` 플래그를 빠뜨리면 워크트리 안에서 `git_common_dir` 가 `../../.git` 같은 상대 경로가 되어 슬러그가 `.-.` 으로 망가진다. - - 디렉토리 없으면 `mkdir -p` 로 생성. 타임스탬프는 KST 기준. -6. **출력** — 저장한 파일의 **전체 내용을 그대로** 반환한다. 맨 앞에 `💾 저장됨: <절대경로>` 한 줄 추가. +시니어 개발자가 주니어들에게 업무를 분담하듯, 현재 프로젝트 작업을 충돌 없는 병렬 묶음으로 쪼개고 각 묶음의 worktree 시작 프롬프트를 생성한다. + +## 인수 + +- 없음 → 프로젝트 전체 대상 +- `phase-N` 또는 task 번호 목록 → 해당 범위만 + +## Phase 1 — 현황 수집 + +`tasks/`, `specs/`, `DEPENDENCIES.md`, `git worktree list`, 최근 커밋을 읽는다. `scripts/task-status.ts` 같은 상태 스크립트가 있으면 먼저 실행. + +## Phase 2 — 병렬성 판단 + +각 후보의 `depends_on` 충족 + 파일/패턴 충돌 여부로 그룹화. **같은 그룹의 task 는 동시에 worktree 를 열어도 안전해야 한다.** + +## Phase 3 — 브랜치명 추천 + +`git log` 로 기존 컨벤션 확인 후 `worktree-task-{번호}` 또는 `worktree-task-{범위}x` 제안. + +## Phase 4 — 프롬프트 생성 + +[templates/prompt.xml](templates/prompt.xml) 을 읽어 각 task 에 채운다. + +## Phase 5 — 파일 저장 + +[templates/output.md](templates/output.md) 포맷대로 채운 전문을 저장: + +``` +~/.claude/split-work/{project-slug}/{YYYY-MM-DD-HHmm}.md +``` + +`{project-slug}` 는 worktree 안에서도 main repo 기준으로 결정: + +```bash +# --path-format=absolute 로 워크트리에서도 main repo 의 .git 절대 경로를 얻는다. +git_common_dir="$(git rev-parse --path-format=absolute --git-common-dir)" +main_repo="$(dirname "$git_common_dir")" +slug="$(basename "$(dirname "$main_repo")")-$(basename "$main_repo")" +# 예: ~/works/runner/web → runner-web +``` + +- basename 만 쓰면 `web` 같은 generic 이름이 다른 repo 와 충돌 — 부모 한 단계를 결합한다. +- **`--path-format=absolute` 를 빠뜨리지 말 것.** 워크트리 안에서 `git_common_dir` 가 `../../.git` 상대 경로가 되어 슬러그가 `.-.` 으로 망가진다. +- 디렉토리 없으면 `mkdir -p`. 타임스탬프는 KST 기준. + +## Phase 6 — 출력 + +저장한 파일의 **전체 내용을 그대로** 반환. 맨 앞에 `💾 저장됨: <절대경로>` 한 줄 추가. ## 출력 규칙 (호출자 assistant 에게) 이 스킬 결과는 **fork 컨텍스트** 에서 반환되어 사용자에겐 직접 보이지 않는다. 호출자 assistant 는: -- `...` XML 블록을 **축약·요약·생략 금지**. 사용자가 다음 worktree 의 첫 메시지로 그대로 복사하는 원본이다. +- `...` XML 블록 **축약·요약·생략 금지** — 사용자가 다음 worktree 첫 메시지로 그대로 복사하는 원본이다. - "위 결과에 포함됨" / "XML 로 첨부됨" 같은 참조 문구로 대체 금지. -- 만약 응답 길이상 부득이 축약한다면, **반드시 `💾 저장됨` 경로를 사용자에게 노출** 해 파일을 직접 열 수 있게 한다. +- 응답 길이상 부득이 축약한다면 **반드시 `💾 저장됨` 경로를 노출** 해 파일을 직접 열 수 있게 한다. ## 자유도 원칙 -구현 에이전트의 판단 영역을 침범하지 않는다. +구현 에이전트의 판단 영역을 침범하지 않는다. "어떻게" 는 에이전트가 스펙을 읽고 스스로 결정한다. - **금지:** 파일 경로·함수명·라이브러리·구현 순서 지시 - **허용:** 사용자 가치·성공 기준·절대 제약(API 계약·보안·순수성·롤백성)·스펙 참조 위치 - -"어떻게" 는 에이전트가 스펙을 읽고 스스로 결정한다. - -## 인수 - -- 없음 → 프로젝트 전체 대상 -- `phase-N` 또는 task 번호 목록 → 해당 범위만 diff --git a/test-commit-push-pr-clean-plugin/.claude-plugin/plugin.json b/test-commit-push-pr-clean-plugin/.claude-plugin/plugin.json index 7a3ec64..ffb13ce 100644 --- a/test-commit-push-pr-clean-plugin/.claude-plugin/plugin.json +++ b/test-commit-push-pr-clean-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "test-commit-push-pr-clean-plugin", "description": "Automates lint, test, commit, push, PR creation, and worktree cleanup workflow", - "version": "1.3.1", + "version": "1.4.0", "author": { "name": "Stefan Cho" } diff --git a/test-commit-push-pr-clean-plugin/.codex-plugin/plugin.json b/test-commit-push-pr-clean-plugin/.codex-plugin/plugin.json index 88f55e7..194e13c 100644 --- a/test-commit-push-pr-clean-plugin/.codex-plugin/plugin.json +++ b/test-commit-push-pr-clean-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "test-commit-push-pr-clean-plugin", "description": "Automates lint, test, commit, push, PR creation, and worktree cleanup workflow", - "version": "1.3.1", + "version": "1.4.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/test-commit-push-pr-clean-plugin/skills/test-commit-push-pr-clean/SKILL.md b/test-commit-push-pr-clean-plugin/skills/test-commit-push-pr-clean/SKILL.md index aef77ea..9b27061 100644 --- a/test-commit-push-pr-clean-plugin/skills/test-commit-push-pr-clean/SKILL.md +++ b/test-commit-push-pr-clean-plugin/skills/test-commit-push-pr-clean/SKILL.md @@ -1,46 +1,44 @@ --- name: test-commit-push-pr-clean -description: Run a branch-safe finish workflow: lint, test, commit, push, create a pull request, and clean merged worktrees. Use when the user asks to finish work, test and commit changes, push a branch, open a PR, or clean completed worktrees. +description: Runs a branch-safe finish workflow that lints, tests, commits, pushes, creates a pull request, and cleans merged worktrees. Use when the user asks to finish work, test and commit changes, push a branch, open a PR, or clean completed worktrees. --- # Test Commit Push PR Clean -Use this skill to finish feature-branch work in a repository. Respect user-provided skip flags such as `--skip lint,test,push,pr,clean`. +Finish feature-branch work end to end. Honor user-provided skip flags such as `--skip lint,test,push,pr,clean`. -## Workflow +## Skip flags -1. Inspect the current repository state with `git status`, `git branch --show-current`, `git worktree list`, and recent commits. -2. Stop before making commits if the current branch is a default branch such as `main`, `master`, or `develop`; tell the user to create a feature branch or worktree. -3. Unless skipped, run the project's lint or format checks when they are discoverable from package scripts or local tooling. -4. Unless skipped, run the project's tests. If coverage is configured, treat coverage regressions as failures to resolve before committing. -5. Group changes into logical commits. Keep unrelated user changes intact and never revert work you did not make. -6. Unless skipped, push the current branch to its upstream or to `origin`. -7. Unless skipped, create a pull request with `gh pr create`, following the repository's title and body conventions. -8. Unless skipped, inspect merged worktrees with `git worktree list` and remove only worktrees that are clearly merged and not the current working tree. +Keys: `lint`, `test`, `push`, `pr`, `clean`. Example: `--skip push,pr,clean`. -## Skip Flags +## Phase 1 — Inspect -Available skip keys are: +- [ ] `git status`, `git branch --show-current`, `git worktree list`, recent commits -- `lint` -- `test` -- `push` -- `pr` -- `clean` +**Never commit on a default branch** (`main`, `master`, `develop`). Stop and tell the user to create a feature branch or worktree. -Example: `--skip push,pr,clean`. +## Phase 2 — Verify (unless skipped) -## Commit Guidance +- [ ] Run lint/format checks discoverable from package scripts or local tooling +- [ ] Run the project's tests; if coverage is configured, treat coverage regressions as failures to resolve before committing -Use conventional commit types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, or `perf`. Prefer a concise Korean title when the repository convention is Korean. +## Phase 3 — Commit -## Pull Request Guidance +Group changes into logical commits. Conventional types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf`. Prefer a concise Korean title when the repository convention is Korean. -Write PR descriptions in Korean when no project-specific convention overrides it. Include: +**Never revert work you did not make.** Keep unrelated user changes intact. -- user-facing summary -- implementation details grouped by area -- tests or checks that passed -- any deployment or manual verification still needed +## Phase 4 — Push and PR (unless skipped) -For the full Claude slash-command template, see `commands/test-commit-push-pr-clean.md`. +- [ ] Push the current branch to its upstream or to `origin` +- [ ] `gh pr create`, following the repository's title and body conventions + +Write the PR body in Korean unless a project convention overrides it. Include: user-facing summary, implementation details grouped by area, tests/checks that passed, and any deployment or manual verification still needed. + +## Phase 5 — Clean (unless skipped) + +Inspect `git worktree list`. Remove only worktrees that are **clearly merged** and **not the current working tree**. + +## Reference + +Full Claude slash-command template: `commands/test-commit-push-pr-clean.md`. From 76e356983b22909c7a6091ee62050663003adad3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Jun 2026 11:51:34 +0000 Subject: [PATCH 3/6] skills: restyle brain-storm, ui-prototype-preview, llm-wiki - brain-storm-plugin 1.3.0, llm-wiki-plugin 1.2.0 - SKILL.md bodies cut to <80 lines; overflow moved to sibling files (report-format.md, design-standard.md) linked one level deep - two-sentence 'Use when' descriptions, all triggers preserved https://claude.ai/code/session_01YPKG1K27VWQWEMcS9NJK1a --- brain-storm-plugin/.claude-plugin/plugin.json | 2 +- brain-storm-plugin/.codex-plugin/plugin.json | 2 +- .../skills/brain-storm/SKILL.md | 137 +++------- .../skills/brain-storm/report-format.md | 24 ++ .../skills/ui-prototype-preview/SKILL.md | 255 +++++------------- .../ui-prototype-preview/design-standard.md | 69 +++++ .../ui-prototype-preview/report-format.md | 24 ++ llm-wiki-plugin/.claude-plugin/plugin.json | 2 +- llm-wiki-plugin/.codex-plugin/plugin.json | 2 +- llm-wiki-plugin/skills/llm-wiki/SKILL.md | 24 +- 10 files changed, 235 insertions(+), 306 deletions(-) create mode 100644 brain-storm-plugin/skills/brain-storm/report-format.md create mode 100644 brain-storm-plugin/skills/ui-prototype-preview/design-standard.md create mode 100644 brain-storm-plugin/skills/ui-prototype-preview/report-format.md diff --git a/brain-storm-plugin/.claude-plugin/plugin.json b/brain-storm-plugin/.claude-plugin/plugin.json index 31f1fbf..fea8346 100644 --- a/brain-storm-plugin/.claude-plugin/plugin.json +++ b/brain-storm-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "brain-storm-plugin", "description": "Brainstorm future features and improvements, then generate standalone HTML previews for UI ideas", - "version": "1.2.4", + "version": "1.3.0", "author": { "name": "Stefan Cho" } diff --git a/brain-storm-plugin/.codex-plugin/plugin.json b/brain-storm-plugin/.codex-plugin/plugin.json index 0378f1c..5200f49 100644 --- a/brain-storm-plugin/.codex-plugin/plugin.json +++ b/brain-storm-plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "brain-storm-plugin", "description": "Brainstorm future features and improvements, then generate standalone HTML previews for UI ideas", - "version": "1.2.4", + "version": "1.3.0", "skills": "./skills/", "author": { "name": "Stefan Cho" diff --git a/brain-storm-plugin/skills/brain-storm/SKILL.md b/brain-storm-plugin/skills/brain-storm/SKILL.md index cf59aeb..c298deb 100644 --- a/brain-storm-plugin/skills/brain-storm/SKILL.md +++ b/brain-storm-plugin/skills/brain-storm/SKILL.md @@ -1,6 +1,6 @@ --- name: brain-storm -description: Brainstorm future features and improvements based on the current codebase. This is the ideation step before writing specs. Use when the user asks to brainstorm ideas, generate feature ideas, explore improvements, review future opportunities, or clean up outdated brainstorm notes. +description: Brainstorms grounded feature ideas from the current codebase and saves them as wireframed notes in `brain-storm/` — the ideation step before writing specs. Use when the user asks to brainstorm ideas, generate feature ideas, explore improvements, review future opportunities, or clean up outdated brainstorm notes. allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion context: fork agent: general-purpose @@ -8,124 +8,65 @@ agent: general-purpose # Brain Storm -Use this skill before `/writing-specs` to explore what could be built next. The skill scans the codebase, proposes grounded ideas, adds lightweight wireframes, and saves selected ideas into the `brain-storm/` directory for later refinement. +Ideation before `/writing-specs`. Scan the codebase, propose grounded ideas, attach ASCII wireframes, save selected ideas to `brain-storm/`. -## Two Modes +## Modes -This skill supports two modes. Pick the mode that matches the user's request. +- **Brainstorm** — generate, compare, and save new ideas. +- **Cleanup** — detect already-implemented notes and remove them after confirmation. Triggered by "clean up brainstorm notes" or "remove ideas that are already implemented". -- **Brainstorm Mode**: Generate, compare, and save new ideas. -- **Cleanup Mode**: Review existing brainstorm notes, detect already-implemented ideas, and remove them after user confirmation. +## Hard Rules -## Principles - -1. **Explore before proposing** - Understand the codebase before suggesting ideas. -2. **Diverge then converge** - Generate multiple strong options before asking the user to choose. -3. **One idea = one file** - Store each meaningful idea as its own markdown file. -4. **Always visualize** - Every saved idea should include a simple ASCII wireframe or system sketch so the implementation direction is easier to discuss. -5. **Prune the implemented** - Cleanup mode should remove stale brainstorm notes only after evidence-based verification and user approval. - -## Directory Rules - -- Ideas live in `brain-storm/` at the project root. -- File format: `brain-storm/{name}.md` or `brain-storm/{subdir}/{name}.md`. -- Only one directory level is allowed under `brain-storm/`. -- Filenames must use lowercase-with-hyphens. -- Create subdirectories only when the user requests grouping or when five or more ideas share the same domain. - ---- +- Ideas live in `brain-storm/{name}.md` or `brain-storm/{subdir}/{name}.md`. One subdirectory level max; filenames lowercase-with-hyphens. +- Create subdirectories only when the user asks for grouping or 5+ ideas share a domain. +- **One idea = one file**, and every saved idea includes an ASCII wireframe or system sketch. +- Ground every idea in the actual codebase — explore before proposing, diverge before converging. +- **Never delete a brainstorm note without evidence-based verification and explicit user approval.** ## Brainstorm Mode -### Step 1: Scan and Ideate - -1. Run `Glob` on important project directories such as `src/**`, `app/**`, `pages/**`, `components/**`, and `lib/**` to understand the structure. -2. Run `Glob brain-storm/**/*.md` to inspect existing brainstorm notes. -3. Read `package.json`, `README.md`, and any obvious entry-point files to understand the product and stack. -4. Generate 3-5 ideas based on the scan. For each idea, present: - - **Title** - - **Description**: 1-2 sentences - - **Complexity**: Low / Medium / High - - **Quick wireframe sketch**: 3-5 lines of ASCII to give a visual sense of the idea -5. Ask the user which ideas to save. +### Phase 1 — Scan and ideate -Ideas must be grounded in the actual codebase, actionable, and varied in scope. +1. `Glob` key directories (`src/**`, `app/**`, `pages/**`, `components/**`, `lib/**`); read `package.json`, `README.md`, and obvious entry points. +2. `Glob brain-storm/**/*.md` to inspect existing notes. +3. Propose 3-5 ideas, each with **Title**, 1-2 sentence **Description**, **Complexity** (Low/Medium/High), and a 3-5 line ASCII sketch. Make them actionable and varied in scope. +4. Ask the user which ideas to save. -### Step 2: Deduplicate and Write +### Phase 2 — Deduplicate and write For each selected idea: -1. Extract 3-5 key nouns from the title and description. -2. Run `Grep` across `brain-storm/**/*.md` for those keywords. -3. If a duplicate or near-duplicate exists, ask whether to update the existing file, create a new file, or skip it. -4. Read the idea template at `templates/idea-template.md`. -5. Read the wireframe guide at `templates/wireframe-guide.md`. -6. Fill every section: - - **Summary**: 1-2 sentences - - **Motivation**: 2-4 sentences referencing specific codebase areas - - **Proposed Approach**: 3-7 bullet points without code snippets - - **Wireframe**: ASCII art in a fenced code block, at least 10 lines - - **Complexity**: Low / Medium / High with a one-sentence reason - - **Open Questions**: 1-3 bullets -7. Write the completed idea file under `brain-storm/`. - -### Step 3: Report - -After writing all idea files, include this report in the final response: - -```markdown -## Brain Storm Report - -| Field | Value | -|-------|-------| -| Action | Created / Updated | -| Ideas Proposed | {count} | -| Ideas Saved | {count} | - -### Saved Ideas -| File | Title | Complexity | -|------|-------|-----------| -| `{path}` | {title} | {complexity} | - -### Next Steps -- Refine an idea into a spec (recommended — pass the file path so writing-specs reads it directly): - `/writing-specs brain-storm/{file-name}.md` - (Title or keyword also works: `/writing-specs "{idea title}"`) -- Generate a UI prototype preview for a UI-focused idea: `/ui-prototype-preview {idea title}` -``` - -The report must be part of the final response, not a separate file. +- [ ] `Grep` `brain-storm/**/*.md` for 3-5 key nouns from the title/description. On a duplicate or near-duplicate, ask whether to update the existing file, create new, or skip. +- [ ] Read `templates/idea-template.md` and `templates/wireframe-guide.md`. +- [ ] Fill every section — Summary (1-2 sentences), Motivation (2-4 sentences referencing specific codebase areas), Proposed Approach (3-7 bullets, no code snippets), Wireframe (fenced ASCII, at least 10 lines), Complexity (with one-sentence reason), Open Questions (1-3 bullets). +- [ ] Write the file under `brain-storm/`. ---- - -## Cleanup Mode +### Phase 3 — Report -Triggered by requests such as "clean up brainstorm notes" or "remove ideas that are already implemented". +Include the report from [report-format.md](report-format.md) in the final response. **The report is part of the response, never a separate file.** -### Step 1: Detect Implemented Ideas +## Cleanup Mode -1. Run `Glob brain-storm/**/*.md` to list all idea files. -2. For each idea: - a. Read the file and extract the title and summary. - b. Extract 3-5 implementation-indicator keywords such as component names, function names, routes, or API endpoints. - c. Run `Grep` for those keywords in the source code while excluding `brain-storm/`, `specs/`, `node_modules/`, and `.git/`. - d. Mark the idea as implemented only if multiple matches clearly represent the described functionality rather than TODOs or naming coincidence. +### Phase 1 — Detect implemented ideas -### Step 2: Confirm and Delete +1. `Glob brain-storm/**/*.md` to list all notes. +2. For each: read it, extract title and summary, then extract 3-5 implementation-indicator keywords (component names, function names, routes, API endpoints). +3. `Grep` those keywords in source code, excluding `brain-storm/`, `specs/`, `node_modules/`, `.git/`. +4. Mark implemented **only** when multiple matches clearly represent the described functionality — not TODOs or naming coincidence. -1. Present the implemented candidates with supporting evidence. -2. Ask the user whether to delete all, delete selected ideas, or cancel. -3. Delete files only after explicit confirmation. -4. Report the result with status and evidence for each reviewed idea. +### Phase 2 — Confirm and delete ---- +- [ ] Present implemented candidates with supporting evidence. +- [ ] Ask the user — delete all, delete selected, or cancel. +- [ ] Delete only after explicit confirmation. +- [ ] Report status and evidence for each reviewed idea. -## Non-interactive defaults +## Non-interactive Defaults -If the harness signals non-interactive mode (auto mode, scheduled run, headless agent — i.e. `AskUserQuestion` is unavailable or the user has stated "automatic" / "no questions"), use these defaults instead of asking. **Always echo the defaulted decisions back in the final report so the user can override.** +If `AskUserQuestion` is unavailable (auto mode, scheduled run, headless agent) or the user said "automatic" / "no questions", use these defaults. **Always echo the defaulted decisions in the final report so the user can override.** | Decision point | Default | Rationale | |---|---|---| -| Which ideas to save (Brainstorm Step 1) | Save 2 ideas: pick the most diverse pair (1 UX/polish + 1 new capability), preferring Low/Medium complexity. | Diversity beats volume; low-complexity proves out the workflow without committing to large work. | -| Duplicate detected (Brainstorm Step 2) | Skip writing the new file. | Never overwrite user-authored notes silently. | -| Cleanup deletion (Cleanup Step 2) | **Refuse**: report candidates only, do not delete. | Deletion is unrecoverable; require an explicit follow-up command. | +| Which ideas to save (Brainstorm Phase 1) | Save 2 ideas: the most diverse pair (1 UX/polish + 1 new capability), preferring Low/Medium complexity. | Diversity beats volume; low complexity proves the workflow without committing to large work. | +| Duplicate detected (Brainstorm Phase 2) | Skip writing the new file. | Never overwrite user-authored notes silently. | +| Cleanup deletion (Cleanup Phase 2) | **Refuse** — report candidates only, do not delete. | Deletion is unrecoverable; require an explicit follow-up command. | diff --git a/brain-storm-plugin/skills/brain-storm/report-format.md b/brain-storm-plugin/skills/brain-storm/report-format.md new file mode 100644 index 0000000..bcbb217 --- /dev/null +++ b/brain-storm-plugin/skills/brain-storm/report-format.md @@ -0,0 +1,24 @@ +# Brain Storm Report Format + +Include this report (filled in) in the final response after writing all idea files. It must be part of the response, not a separate file. + +```markdown +## Brain Storm Report + +| Field | Value | +|-------|-------| +| Action | Created / Updated | +| Ideas Proposed | {count} | +| Ideas Saved | {count} | + +### Saved Ideas +| File | Title | Complexity | +|------|-------|-----------| +| `{path}` | {title} | {complexity} | + +### Next Steps +- Refine an idea into a spec (recommended — pass the file path so writing-specs reads it directly): + `/writing-specs brain-storm/{file-name}.md` + (Title or keyword also works: `/writing-specs "{idea title}"`) +- Generate a UI prototype preview for a UI-focused idea: `/ui-prototype-preview {idea title}` +``` diff --git a/brain-storm-plugin/skills/ui-prototype-preview/SKILL.md b/brain-storm-plugin/skills/ui-prototype-preview/SKILL.md index a09e58c..f9497b2 100644 --- a/brain-storm-plugin/skills/ui-prototype-preview/SKILL.md +++ b/brain-storm-plugin/skills/ui-prototype-preview/SKILL.md @@ -1,6 +1,6 @@ --- name: ui-prototype-preview -description: Generate a distinctive standalone HTML preview from a saved UI brainstorm idea. Use when the user wants to visualize a brainstorm idea as a concrete mockup, prototype, preview, landing page, dashboard, or product screen with strong design quality. +description: Generates a distinctive standalone HTML preview from a saved UI brainstorm idea. Use when the user wants to visualize a brainstorm idea as a concrete mockup, prototype, preview, landing page, dashboard, or product screen with strong design quality. allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion context: fork agent: general-purpose @@ -8,191 +8,68 @@ agent: general-purpose # UI Prototype Preview -Generate a self-contained HTML prototype from a saved brainstorm idea. This skill should produce a visually distinctive concept, not a generic AI-looking dashboard. Use it after `brain-storm` when a UI-focused idea needs a stronger visual artifact before specification or implementation. - -## Principles - -1. **Start from saved intent** - Prefer an existing file in `brain-storm/` instead of inventing a product direction from scratch. -2. **Concept first, code second** - Commit to a clear aesthetic direction before writing any HTML. -3. **Design brief over overloaded arguments** - Prefer a reusable `DESIGN.md` file when there are many constraints, brand tokens, or variant requests. -4. **Prototype, do not under-design** - The goal is not production code, but the result must still feel deliberate, polished, and memorable. -5. **One standout idea** - Every preview should have a single memorable visual or interaction moment that defines the concept. -6. **Avoid generic AI aesthetics** - Do not default to bland SaaS cards, overused purple-on-white palettes, or interchangeable layouts. -7. **Traceability** - Report which brainstorm file the preview came from, what design direction you chose, which design brief you used, and where the HTML was saved. - -## Output Rules - -- Save previews to `brain-storm/previews/{idea-name}.html`. -- For multi-variant runs, save files to `brain-storm/previews/{idea-name}-{variant-slug}.html`. -- Save design briefs to `brain-storm/design/{idea-name}-design.md` unless the user provides a different path. -- Use lowercase-with-hyphens for filenames. -- Create `brain-storm/previews/` and `brain-storm/design/` if they do not exist. -- The HTML must be standalone with embedded `