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/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/brain-storm-plugin/.claude-plugin/plugin.json b/brain-storm-plugin/.claude-plugin/plugin.json index 31f1fbf..4c015a4 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.1", "author": { "name": "Stefan Cho" } diff --git a/brain-storm-plugin/.codex-plugin/plugin.json b/brain-storm-plugin/.codex-plugin/plugin.json index 0378f1c..2ced955 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.1", "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..426d26b 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". +Fill [templates/report-template.md](templates/report-template.md) and include it 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 (Implementation Check section of [templates/report-template.md](templates/report-template.md)). -## 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/templates/report-template.md b/brain-storm-plugin/skills/brain-storm/templates/report-template.md index 2ed8e5f..4e7f897 100644 --- a/brain-storm-plugin/skills/brain-storm/templates/report-template.md +++ b/brain-storm-plugin/skills/brain-storm/templates/report-template.md @@ -18,5 +18,6 @@ - {idea path} - {Implemented (deleted) / Implemented (kept) / Not yet implemented} ### Next Steps -- Refine a saved idea into a spec with `/writing-specs {idea title}` +- 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 an HTML preview for a UI-focused idea with `/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..fb94410 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 `