@anionzo/skill 1.4.0 → 1.7.0

package/scripts/install-opencode-skills

@@ -1,4 +1,4 @@
-#!/usr/bin/env sh
+#!/usr/bin/env bash
 
 # Install AI skills into agent-specific directories
 #
@@ -10,14 +10,20 @@
 #   npm install @anionzo/skill      # auto (postinstall)
 #   bash scripts/install-opencode-skills [project-dir]
 
-set -eu
+set -euo pipefail
 
 SCRIPT_PATH=$(readlink -f "$0" 2>/dev/null || realpath "$0" 2>/dev/null || echo "$0")
 ROOT=$(CDPATH= cd -- "$(dirname "$SCRIPT_PATH")/.." && pwd)
 
-# Determine project root: explicit arg > INIT_CWD (set by npm) > current dir
+# Determine project root:
+#   1. explicit arg
+#   2. npm_config_local_prefix during lifecycle scripts (correct for npm install --prefix)
+#   3. INIT_CWD (npm invocation cwd)
+#   4. current dir
 if [ -n "${1:-}" ]; then
   PROJECT="$1"
+elif [ "${npm_lifecycle_event:-}" = "postinstall" ] && [ -n "${npm_config_local_prefix:-}" ]; then
+  PROJECT="$npm_config_local_prefix"
 elif [ -n "${INIT_CWD:-}" ]; then
   PROJECT="$INIT_CWD"
 else
@@ -135,8 +141,180 @@ copilot||.github/copilot-instructions.md|GitHub Copilot Instructions|GitHub Copi
 # --- Interactive mode detection ---
 
 is_interactive() {
-  # postinstall (npm) sets INIT_CWD — skip interactive
-  [ -z "${INIT_CWD:-}" ] && [ -t 0 ]
+  [ "${npm_lifecycle_event:-}" != "postinstall" ] && [ -t 0 ] && [ -t 1 ]
+}
+
+# --- Interactive picker ---
+
+MENU_LABELS=(
+  "OpenCode        (.opencode/skills/ + OPENCODE.md)"
+  "Claude Code     (.claude/skills/   + CLAUDE.md)"
+  "Agents (generic)(.agents/skills/   + AGENTS.md)"
+  "Gemini CLI      (GEMINI.md)"
+  "GitHub Copilot  (.github/copilot-instructions.md)"
+  "Update .gitignore with selected platform files"
+)
+
+read_key() {
+  local key rest final
+
+  IFS= read -rsn1 key || return 1
+
+  if [ "$key" = $'\x1b' ]; then
+    IFS= read -rsn1 -t 0.1 rest || true
+    if [ "$rest" = "[" ]; then
+      IFS= read -rsn1 -t 0.1 final || true
+      printf '\033[%s' "$final"
+    else
+      printf '\033%s' "$rest"
+    fi
+    return 0
+  fi
+
+  printf '%s' "$key"
+}
+
+render_menu() {
+  local cursor="$1"
+  shift
+  local -a state=("$@")
+  local i mark prefix
+
+  printf '\033[H\033[2J'
+  printf '\n'
+  printf '  @anionzo/skill -- AI Skill Library\n'
+  printf '  ==================================\n\n'
+  printf '  Use arrow keys to move, space to toggle, enter to install.\n'
+  printf '  Press a to toggle all platforms, q to cancel.\n\n'
+
+  for i in "${!MENU_LABELS[@]}"; do
+    [ "$i" -eq 5 ] && printf '\n'
+
+    if [ "${state[$i]}" -eq 1 ]; then
+      mark='[x]'
+    else
+      mark='[ ]'
+    fi
+
+    if [ "$i" -eq "$cursor" ]; then
+      prefix='>'
+    else
+      prefix=' '
+    fi
+
+    printf '  %s %s %s\n' "$prefix" "$mark" "${MENU_LABELS[$i]}"
+  done
+
+  printf '\n'
+}
+
+toggle_all_platforms() {
+  local -n state_ref=$1
+  local sum=0
+  local i next=1
+
+  for i in 0 1 2 3 4; do
+    sum=$((sum + state_ref[$i]))
+  done
+
+  [ "$sum" -eq 5 ] && next=0
+
+  for i in 0 1 2 3 4; do
+    state_ref[$i]=$next
+  done
+}
+
+interactive_select() {
+  local cursor=0
+  local key
+  local -a selected=(0 0 0 0 0 0)
+
+  while true; do
+    render_menu "$cursor" "${selected[@]}"
+    key=$(read_key) || exit 0
+
+    case "$key" in
+      $'\033[A')
+        if [ "$cursor" -eq 0 ]; then
+          cursor=$((${#MENU_LABELS[@]} - 1))
+        else
+          cursor=$((cursor - 1))
+        fi
+        ;;
+      $'\033[B')
+        if [ "$cursor" -eq $((${#MENU_LABELS[@]} - 1)) ]; then
+          cursor=0
+        else
+          cursor=$((cursor + 1))
+        fi
+        ;;
+      "")
+        break
+        ;;
+      " ")
+        if [ "${selected[$cursor]}" -eq 1 ]; then
+          selected[$cursor]=0
+        else
+          selected[$cursor]=1
+        fi
+        ;;
+      [aA])
+        toggle_all_platforms selected
+        ;;
+      [qQ])
+        printf '\n  Cancelled.\n\n'
+        exit 0
+        ;;
+    esac
+  done
+
+  printf '%s\n' "${selected[@]}"
+}
+
+update_gitignore() {
+  local gitignore="$PROJECT/.gitignore"
+  local -a entries=()
+  local -a missing=()
+  local header_needed=0
+  local entry
+
+  [ "${do_opencode:-0}" -eq 1 ] && entries+=(".opencode/" "OPENCODE.md")
+  [ "${do_claude:-0}" -eq 1 ] && entries+=(".claude/" "CLAUDE.md")
+  [ "${do_agents:-0}" -eq 1 ] && entries+=(".agents/" "AGENTS.md")
+  [ "${do_gemini:-0}" -eq 1 ] && entries+=("GEMINI.md")
+  [ "${do_copilot:-0}" -eq 1 ] && entries+=(".github/copilot-instructions.md")
+
+  if [ "${#entries[@]}" -eq 0 ]; then
+    printf '  .gitignore: skipped (no platform files selected)\n'
+    return
+  fi
+
+  touch "$gitignore"
+
+  if ! grep -Fqx '# @anionzo/skill' "$gitignore" 2>/dev/null; then
+    header_needed=1
+  fi
+
+  for entry in "${entries[@]}"; do
+    if ! grep -Fqx "$entry" "$gitignore" 2>/dev/null; then
+      missing+=("$entry")
+    fi
+  done
+
+  if [ "${#missing[@]}" -eq 0 ]; then
+    printf '  .gitignore: already up to date -> %s\n' "$gitignore"
+    return
+  fi
+
+  if [ "$header_needed" -eq 1 ]; then
+    printf '\n# @anionzo/skill\n' >> "$gitignore"
+  fi
+
+  for entry in "${missing[@]}"; do
+    printf '%s\n' "$entry" >> "$gitignore"
+  done
+
+  printf '  .gitignore: added %d entries -> %s\n' "${#missing[@]}" "$gitignore"
 }
 
 # --- Main ---
@@ -146,36 +324,16 @@ printf '  @anionzo/skill — AI Skill Library\n'
 printf '  ==================================\n\n'
 
 if is_interactive; then
-  # --- Interactive: let user pick platforms ---
-
-  printf '  Which platforms do you want to install?\n\n'
-  printf '  [1] OpenCode        (.opencode/skills/ + OPENCODE.md)\n'
-  printf '  [2] Claude Code     (.claude/skills/   + CLAUDE.md)\n'
-  printf '  [3] Agents (generic)(.agents/skills/   + AGENTS.md)\n'
-  printf '  [4] Gemini CLI      (GEMINI.md)\n'
-  printf '  [5] GitHub Copilot  (.github/copilot-instructions.md)\n'
-  printf '  [a] All of the above\n\n'
-
-  printf '  Enter choices (e.g. 1 2 3, or a for all): '
-  read -r choices
-
-  # Normalize
-  case "$choices" in
-    *[aA]*) choices="1 2 3 4 5" ;;
-  esac
-
-  # Parse choices into flags
-  do_opencode=0; do_claude=0; do_agents=0; do_gemini=0; do_copilot=0
-
-  for c in $choices; do
-    case "$c" in
-      1) do_opencode=1 ;;
-      2) do_claude=1 ;;
-      3) do_agents=1 ;;
-      4) do_gemini=1 ;;
-      5) do_copilot=1 ;;
-    esac
-  done
+  # --- Interactive: let user pick platforms with arrows + space ---
+
+  mapfile -t selected < <(interactive_select)
+
+  do_opencode=${selected[0]}
+  do_claude=${selected[1]}
+  do_agents=${selected[2]}
+  do_gemini=${selected[3]}
+  do_copilot=${selected[4]}
+  do_gitignore=${selected[5]}
 
   # Check if anything was selected
   total=$((do_opencode + do_claude + do_agents + do_gemini + do_copilot))
@@ -213,6 +371,10 @@ if is_interactive; then
     printf '  -> .github/copilot-instructions.md\n'
   fi
 
+  if [ "$do_gitignore" -eq 1 ]; then
+    update_gitignore
+  fi
+
 else
   # --- Silent mode: postinstall — install all skill dirs, no agent files ---
 

package/skills/brainstorming/SKILL.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Refine a fuzzy request into a concrete direction that is clear enough to plan.
+Refine a fuzzy request into a concrete direction, and when needed, lock decisions into a specification before implementation begins.
+
+This skill combines idea exploration with spec-driven development: first clarify what to build, then optionally formalize it into a spec with locked decisions and acceptance criteria.
 
 ## When To Use
 
@@ -11,35 +13,196 @@ Load this skill when:
 - the user has an idea but not a settled approach
 - the scope or success criteria are still unclear
 - multiple reasonable options exist and the tradeoff matters
-- starting implementation immediately would force too many assumptions
+- the user says "spec this", "define requirements", or "what should we build"
+- planning a non-trivial feature that has ambiguous requirements
+- multiple stakeholders need to agree on behavior before code is written
 
 Skip this skill and go directly to `planning` when the request is already specific: a named feature with clear scope, a known code path, or an explicit task with acceptance criteria.
 
-## Workflow
+## Workflow Overview
+
+**Phase 0: Explore** — clarify the idea, surface tradeoffs, extract decisions
+**Phase 1: Lock Direction** — lock the recommended direction and scope boundary
+**Phase 2: Write Spec** (optional) — formalize into a spec document with ACs
+**Phase 3: Review** — get user approval before handoff
+
+For simple clarifications, Phase 0 + Phase 1 is sufficient. For non-trivial features, continue through Phase 2 + Phase 3.
+
+## Phase 0: Explore
+
+### 0.1 Scope Assessment
+
+Assess the request complexity:
+
+- **Quick** — bounded, low ambiguity (rename a flag, tweak a label). Clarify and hand off to `planning`.
+- **Standard** — normal feature with decisions to extract. Run full exploration.
+- **Deep** — cross-cutting, strategic, or highly ambiguous. Run exploration with extra depth, then write a spec.
+
+### 0.2 Restate and Question
 
 1. Restate the request in plain language.
 2. Ask focused questions that reduce ambiguity quickly.
 3. Surface the most important tradeoffs, not every possible one.
-4. Propose one or two viable directions with clear consequences.
-5. Lock the current best direction, scope boundary, and open questions.
-6. End with a handoff into `planning` when the request is concrete enough.
+
+**HARD RULE: Ask ONE question at a time. Wait for the user's response before asking the next.**
+
+Rules:
+
+- One question per message — never bundled
+- Single-select multiple choice preferred over open-ended
+- Start broad (what/why/for whom) then narrow (constraints, edge cases)
+- 3-4 questions per topic area, then checkpoint:
+  > "More questions about [area], or move on? (Remaining: [unvisited areas])"
+
+### 0.3 Gray Area Identification
+
+Generate 2-4 gray areas — decisions that affect implementation but were not stated in the request. A gray area is a decision that would force the planner to make an assumption without it.
+
+Quick codebase scout (grep, not deep analysis):
+
+- check what already exists that is related
+- annotate options with what the codebase already has
+
+Filter OUT:
+
+- technical implementation details (architecture, library choices) — that is `planning`'s job
+- performance concerns
+- scope expansion (new capabilities not requested)
+
+### 0.4 Decision Locking
+
+After each gray area is resolved, lock the decision:
+
+> "Lock decision D[N]: [summary]. Confirmed?"
+
+Assign stable IDs: D1, D2, D3... These IDs carry forward into the spec.
+
+**Scope creep response** — when the user suggests something outside scope:
+
+> "[Feature X] is a new capability — noted as a separate work item. Back to [current area]: [question]"
+
+## Phase 1: Lock Direction
+
+Summarize the exploration output. All three of the following must be written down explicitly:
+
+1. **Recommended direction** — the approach to take
+2. **At least one key constraint** — what limits or shapes the solution
+3. **Scope boundary** — what is in and what is out
+
+Present viable options with consequences if multiple exist, but recommend one.
+
+**For quick scope:** This is the final output. Hand off to `planning`.
+
+**For standard/deep scope:** Continue to Phase 2.
+
+## Phase 2: Write Spec (For Standard/Deep Scope)
+
+### Spec Document Structure
+
+```markdown
+## Overview
+
+Brief description of the feature and its purpose.
+
+## Locked Decisions
+
+- D1: [Decision summary]
+- D2: [Decision summary]
+
+## Requirements
+
+### Functional Requirements
+- FR-1: [Requirement description]
+- FR-2: [Requirement description]
+
+### Non-Functional Requirements
+- NFR-1: [Performance, security, etc.]
+
+## Acceptance Criteria
+
+- [ ] AC-1: [Testable criterion]
+- [ ] AC-2: [Testable criterion]
+
+## Scenarios
+
+### Scenario 1: [Happy Path]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+### Scenario 2: [Edge Case]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+## Open Questions
+
+- [ ] Question 1?
+```
+
+### Spec Quality Rules
+
+- Requirements must be testable.
+- Acceptance criteria must be observable outcomes, not vague goals.
+- Scenarios should cover the happy path plus important edge cases.
+- Open questions must stay explicit, not buried in prose.
+- Keep the spec focused on WHAT, not HOW (implementation is `planning`'s job).
+
+## Phase 3: Review
+
+Present the spec (or the locked direction for quick scope) and ask:
+
+> Please review:
+> - **Approve** if complete
+> - **Edit** if you want to modify something
+> - **Add more** if requirements are missing
+
+Handle the response:
+
+- **Approved** → hand off to next skill
+- **Edit requested** → update, return to review
+- **Add more** → gather additional requirements, update, return to review
 
 ## Output Format
 
-- clarified goal
-- constraints and assumptions
-- viable options considered
-- recommended direction
-- unresolved questions
-- next skill to invoke
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the clarified direction, spec (if written), and approval status
+2. **Key Details:**
+   - locked decisions (D1, D2...)
+   - scope boundary (in/out)
+   - viable options considered with tradeoffs
+   - acceptance criteria (if spec written)
+   - open questions
+3. **Next Action** — after approval:
+    - to review each step: `planning` (with spec reference)
+    - to execute everything at once: `planning` in go mode (with spec reference)
+    - if requirements still unclear: state what decision is still needed
 
 ## Red Flags
 
 - diving into file-level implementation too early
 - asking many questions that do not change the decision
+- batching multiple questions in one message (HARD RULE violation)
 - presenting vague options with no tradeoff explanation
 - pretending the problem is settled when key constraints are still unknown
+- creating a spec without user input
+- answering your own questions during exploration
+- skipping the review step
+- writing implementation notes instead of requirements
+- leaving ambiguous acceptance criteria that cannot be verified
+
+## Checklist
+
+- [ ] Scope assessed (quick/standard/deep)
+- [ ] Request restated in plain language
+- [ ] Gray areas identified and explored (one question at a time)
+- [ ] Decisions locked with stable IDs (D1, D2...)
+- [ ] Direction, constraint, and scope boundary documented
+- [ ] Spec written (if standard/deep scope): overview, decisions, requirements, ACs, scenarios
+- [ ] User reviewed and approved
+- [ ] Next step communicated
 
 ## Done Criteria
 
-This skill is complete when all three of the following are written down explicitly: the recommended direction, at least one key constraint, and the scope boundary. At that point, `planning` can proceed without inventing missing requirements.
+This skill is complete when the recommended direction, at least one key constraint, and the scope boundary are all written down explicitly. For standard/deep scope, the spec must be approved with acceptance criteria defined. If the spec is not approved, the skill is complete when the user has the information needed to make a decision.

package/skills/brainstorming/meta.yaml

@@ -1,23 +1,31 @@
 name: brainstorming
-version: 0.1.0
+version: 0.2.0
 category: discovery
-summary: Turn a rough idea or underspecified request into a concrete, reviewable direction before planning begins.
-summary_vi: Biến ý tưởng thô hoặc request chưa rõ thành hướng đi cụ thể, có thể review, trước khi bắt đầu lập plan.
+summary: Turn a rough idea into a concrete direction with locked decisions, optionally formalized into a spec with acceptance criteria.
+summary_vi: "Biến ý tưởng thô thành hướng đi cụ thể với quyết định đã khóa, có thể formalize thành spec với acceptance criteria."
 triggers:
   - help me think this through
   - explore the approach first
   - the request is vague or underspecified
+  - spec this feature
+  - define requirements
+  - what should we build
+  - create a specification
 inputs:
-  - rough idea
+  - rough idea or feature description
   - user goals and constraints
 outputs:
-  - clarified goal
-  - key decisions
-  - open questions
-  - handoff into planning
+  - clarified goal and direction
+  - locked decisions (D1, D2...)
+  - scope boundary
+  - optional spec with requirements and ACs
+  - approval status
 constraints:
-  - avoid jumping into code or low-level implementation too early
-  - keep the discussion concrete and decision-oriented
+  - ask one question at a time during exploration
+  - do not skip the review step
+  - keep focused on WHAT not HOW
 related_skills:
   - using-skills
   - planning
+  - research
+  - feature-delivery