opencode-froggy 0.9.0 → 0.10.0

package/README.md

@@ -7,7 +7,7 @@
   <a href="https://www.npmjs.com/package/opencode-froggy"><img src="https://badge.fury.io/js/opencode-froggy.svg" alt="npm version"></a>
 </p>
 
-OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (code-release), and tools (gitingest, pdf-to-markdown, blockchain queries, agent-promote).
+OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (ask-questions-if-underspecified, tdd), and tools (gitingest, pdf-to-markdown, blockchain queries, agent-promote).
 
 ---
 
@@ -17,7 +17,11 @@ OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubb
 - [Commands](#commands)
 - [Agents](#agents)
 - [Skills](#skills)
-  - [code-release](#code-release)
+  - [Overview](#overview)
+  - [Available Skills](#available-skills)
+  - [Discovery Locations](#discovery-locations)
+  - [Creating a Skill](#creating-a-skill)
+  - [Automatic Activation](#automatic-activation)
 - [Tools](#tools)
   - [gitingest](#gitingest)
   - [prompt-session](#prompt-session)
@@ -117,15 +121,148 @@ Shows stats overview, commits, files changed, and full diff between branches.
 
 ## Skills
 
-Skills are loaded on-demand to provide specialized capabilities during a session.
+Skills are contextual instructions loaded on demand via the `skill` tool. The agent invokes `skill({ name: "skill-name" })` to load the instructions when needed.
 
-### code-release
+### Overview
 
-Prepare releases with version bumps, changelog updates, and tags.
+- Skills provide specialized guidance for specific tasks
+- Instructions are loaded only when explicitly requested
+- Multiple skills can exist with the same name; the highest-priority location wins
 
-- **Purpose**: Guide release preparation steps and require confirmation before changing release artifacts
-- **Activation**: On user request to prepare or perform a release
-- **Constraints**: Avoid changing versions, tags, or changelogs without explicit confirmation
+### Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `ask-questions-if-underspecified` | Clarify requirements before implementing. Use when serious doubts arise. |
+| `tdd` | Apply Test-Driven Development workflow for new features and bugfixes. |
+
+#### Example: ask-questions-if-underspecified
+
+**User request:**
+> "Add authentication to the API"
+
+**Agent response (after loading the skill):**
+
+The agent recognizes this request has multiple interpretations and uses the `question` tool:
+
+```
+┌─ Authentication Approach ────────────────────────────────────────┐
+│                                                                  │
+│  Which authentication method should be implemented?              │
+│                                                                  │
+│  ○ JWT tokens (Recommended)                                      │
+│  ○ Session-based with cookies                                    │
+│  ○ OAuth 2.0 / OpenID Connect                                    │
+│  ○ API keys                                                      │
+│  ○ Other                                                         │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+After the user selects "JWT tokens", the agent confirms:
+
+> "I'll add JWT-based authentication to the API endpoints using the existing Express middleware pattern. Success = all `/api/*` routes require a valid token, with a `/auth/login` endpoint for token generation."
+
+Then implementation begins.
+
+#### Example: tdd
+
+**User request:**
+> "Add a function to calculate the total price with tax"
+
+**Agent response (after loading the skill):**
+
+The agent follows the TDD workflow:
+
+1. **Requirement Synthesis:**
+> "I'll create a function that calculates total price with tax. It should accept a price and tax rate, returning the total."
+
+2. **Test Specification:**
+```typescript
+describe("calculateTotalWithTax", () => {
+  it("should add tax to the base price", () => {
+    expect(calculateTotalWithTax(100, 0.2)).toBe(120)
+  })
+
+  it("should handle zero tax rate", () => {
+    expect(calculateTotalWithTax(100, 0)).toBe(100)
+  })
+})
+```
+
+3. **Implementation:**
+```typescript
+function calculateTotalWithTax(price: number, taxRate: number): number {
+  return price * (1 + taxRate)
+}
+```
+
+The tests are written first (red), then the minimal implementation to pass them (green).
+
+### Discovery Locations
+
+Skills are discovered from the following locations, in order of increasing priority:
+
+| Priority | Scope | Location |
+|----------|-------|----------|
+| 1 (lowest) | plugin | `<plugin>/skill/` |
+| 2 | global | `~/.config/opencode/skill/` |
+| 3 (highest) | project | `<project>/.opencode/skill/` |
+
+If multiple skills share the same name, the one from the highest-priority location takes precedence.
+
+### Creating a Skill
+
+Each skill lives in its own directory with a `SKILL.md` file:
+
+```
+skill/
+└── my-skill/
+    └── SKILL.md
+```
+
+The `SKILL.md` file uses YAML frontmatter for metadata:
+
+```markdown
+---
+name: my-skill
+description: Short description of the skill (required)
+use_when: >
+  Condition for automatic activation (optional).
+---
+
+# Detailed Instructions
+
+Markdown content with step-by-step guidance...
+```
+
+#### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier for the skill |
+| `description` | Yes | Short description (displayed in skill listings) |
+| `use_when` | No | Condition for automatic activation |
+
+A skill without `name` or `description` will be ignored.
+
+### Automatic Activation
+
+If a skill defines `use_when`, a directive is injected into the system prompt:
+
+```
+MANDATORY: Call skill({ name: "my-skill" }) <use_when content>
+```
+
+This instructs the agent to load the skill when the specified condition is met.
+
+**What is injected:**
+- The skill `name`
+- The `use_when` text (normalized: multiple spaces collapsed to single space)
+
+**What is NOT injected:**
+- The `description`
+- The markdown content (loaded only when the skill is invoked)
 
 ---
 

package/agent/code-simplifier.md

@@ -26,6 +26,7 @@ You do not introduce new features, fix bugs, or change logic. You only improve h
 
 ### 2. Scope discipline
 - Only simplify code that was **modified or introduced in the current session**.
+- This includes **untracked files** (new files not yet committed) listed in the working tree.
 - Do not refactor adjacent or pre-existing code unless strictly required to simplify the modified section.
 - No cross-file refactors unless the change itself spans multiple files.
 
@@ -61,11 +62,12 @@ Apply simplifications only when they clearly improve readability or maintainabil
 
 ## Execution process
 
-1. Identify code that was added or modified in the current session.
-2. Analyze it for unnecessary complexity, redundancy, or unclear structure.
-3. Apply minimal, behavior-preserving refinements.
-4. Re-check that functionality, outputs, and side effects are unchanged.
-5. Produce the simplified code.
+1. Identify code that was added or modified in the current session, **including untracked files listed in the diff**.
+2. **Read the content of untracked files** using the Read tool before analyzing them.
+3. Analyze the code for unnecessary complexity, redundancy, or unclear structure.
+4. Apply minimal, behavior-preserving refinements.
+5. Re-check that functionality, outputs, and side effects are unchanged.
+6. Produce the simplified code.
 
 ## Output requirements
 

package/command/commit-push.md

@@ -9,7 +9,7 @@ agent: build
 
 ## Your task
 
-1. Run `/diff-summary` to analyze all working tree changes
+1. /diff-summary to analyze all working tree changes
 2. Present a summary to the user:
    - Files modified/added/deleted with stats
    - Proposed commit message based on the changes

package/command/diff-summary.md

@@ -43,9 +43,8 @@ else
   git diff
 
   echo ""
-  echo "## Untracked Files Content"
-  git ls-files --others --exclude-standard | while read f; do
-    [ -f "$f" ] && echo "=== $f ===" && sed -n "1,50p" "$f" && sed -n "51p" "$f" | grep -q . && echo "... (truncated)"
-  done
+  echo "## Untracked Files (new)"
+  echo "These files are new and not yet tracked by git. Read them directly to see their content."
+  git ls-files --others --exclude-standard
 fi
 '`

package/command/release.md

@@ -4,8 +4,7 @@ description: Prepare and execute a release with version bumping, changelog updat
 
 ## Context
 
-- Current version: !`node -p "require('./package.json').version"`
-- Latest tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "none"`
+- Current version: !`git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0"`
 - Commits since last tag: !`git log $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~10")..HEAD --oneline 2>/dev/null || git log --oneline -10`
 
 ## CRITICAL CONSTRAINT
@@ -20,8 +19,8 @@ Any destructive or remote action requires confirmation, including:
 
 ### Step 1: Determine last released version
 
-1. Prefer the latest Git tag that matches `v<semver>`.
-2. If no matching tag exists, use the version in `package.json`.
+1. Use the latest Git tag that matches `v<semver>` or `<semver>`.
+2. If no tag exists, consider this the first release (`0.0.0`).
 3. Collect commits since the last version (tag to `HEAD`).
 
 ### Step 2: Propose version bump
@@ -35,10 +34,16 @@ Present the recommendation and ask the user to confirm before changing any files
 
 ### Step 3: Update release artifacts (after confirmation)
 
-- Update the version in `package.json`.
 - Update `CHANGELOG` with a new section for the version.
 - Summarize changes based on the commit range.
 - Preserve the existing changelog format.
+- Auto-detect and update the version file if present:
+  - Node.js: `package.json`
+  - Python: `pyproject.toml` or `setup.py`
+  - Rust: `Cargo.toml`
+  - PHP: `composer.json`
+  - Ruby: `*.gemspec`
+  - Go: tags only (no version file)
 
 ### Step 4: Tag and publish (after confirmation)
 

package/command/review-changes.md

@@ -16,7 +16,8 @@ agent: code-reviewer
 !`git diff --stat`
 !`git diff`
 
-## Untracked Files Content
-!`bash -c 'git ls-files --others --exclude-standard | while read f; do [ -f "$f" ] && echo "=== $f ===" && sed -n "1,50p" "$f" && sed -n "51p" "$f" | grep -q . && echo "... (truncated)"; done'`
+## Untracked Files (new)
+These files are new and not yet tracked by git. Read them directly to see their content.
+!`git ls-files --others --exclude-standard`
 
 Review the above changes for quality, correctness, and adherence to project guidelines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-froggy",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "OpenCode plugin with a hook layer (tool.before.*, session.idle...), agents (code-reviewer, doc-writer), and commands (/review-pr, /commit)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skill/tdd/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: tdd
+description: Apply Test-Driven Development workflow for new features and bugfixes.
+---
+
+# TDD Protocol
+
+## Core Principle
+
+- **TDD First**: Test-Driven Development is the default approach.
+- **Goal**: Prioritize behavioral correctness and regression safety over formal compliance.
+
+## Workflow
+
+1. **Requirement Synthesis**: Briefly summarize the requirements before coding.
+2. **Test Specification**: Write tests describing the expected behavior (unit, integration, or E2E).
+3. **Implementation**: Update the logic only to the extent required to satisfy those tests.
+
+## Mandatory Rules
+
+- **No Test, No Code**: Every new feature or bugfix must include relevant test coverage.
+- **Black-Box Testing**: Validate observable behavior, not internal implementation details.
+- **Merge Requirement**: Tests are mandatory for completion unless an explicit exception is documented.
+
+## Preferred Practice
+
+- **Red-Green-Refactor**: Start with a failing test whenever practical.
+- **Right-Sized Testing**:
+  - **Unit Tests**: For pure logic and isolated functions.
+  - **Integration Tests**: For system interactions and API boundaries.
+  - **E2E Tests**: For critical user journeys and "happy paths."
+
+## Explicit Exceptions (Must be justified)
+
+- Pure refactoring (where behavior remains identical).
+- Exploratory spikes or R&D.
+- UI/Styling iterations where unit tests offer diminishing returns.
+- Complex integrations where mocking is counterproductive.
+- Emergency hotfixes (requires a follow-up ticket for test debt).
+
+## Quality Bar
+
+- **Readability**: Tests must serve as documentation for the feature.
+- **Reliability**: Tests must be deterministic (no flakes) and decoupled from implementation internals.