@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/dhh-rails-style/references/testing.md

@@ -0,0 +1,354 @@
+# Testing - DHH Rails Style
+
+## Core Philosophy
+
+"Minitest with fixtures - simple, fast, deterministic." The approach prioritizes pragmatism over convention.
+
+## Why Minitest Over RSpec
+
+- **Simpler**: Less DSL magic, plain Ruby assertions
+- **Ships with Rails**: No additional dependencies
+- **Faster boot times**: Less overhead
+- **Plain Ruby**: No specialized syntax to learn
+
+## Fixtures as Test Data
+
+Rather than factories, fixtures provide preloaded data:
+
+- Loaded once, reused across tests
+- No runtime object creation overhead
+- Explicit relationship visibility
+- Deterministic IDs for easier debugging
+
+### Fixture Structure
+
+```yaml
+# test/fixtures/users.yml
+david:
+  identity: david
+  account: basecamp
+  role: admin
+
+jason:
+  identity: jason
+  account: basecamp
+  role: member
+
+# test/fixtures/rooms.yml
+watercooler:
+  name: Water Cooler
+  creator: david
+  direct: false
+
+# test/fixtures/messages.yml
+greeting:
+  body: Hello everyone!
+  room: watercooler
+  creator: david
+```
+
+### Using Fixtures in Tests
+
+```ruby
+test "sending a message" do
+  user = users(:david)
+  room = rooms(:watercooler)
+
+  # Test with fixture data
+end
+```
+
+### Dynamic Fixture Values
+
+ERB enables time-sensitive data:
+
+```yaml
+recent_card:
+  title: Recent Card
+  created_at: <%= 1.hour.ago %>
+
+old_card:
+  title: Old Card
+  created_at: <%= 1.month.ago %>
+```
+
+## Test Organization
+
+### Unit Tests
+
+Verify business logic using setup blocks and standard assertions:
+
+```ruby
+class CardTest < ActiveSupport::TestCase
+  setup do
+    @card = cards(:one)
+    @user = users(:david)
+  end
+
+  test "closing a card creates a closure" do
+    assert_difference -> { Card::Closure.count } do
+      @card.close(creator: @user)
+    end
+
+    assert @card.closed?
+    assert_equal @user, @card.closure.creator
+  end
+
+  test "reopening a card destroys the closure" do
+    @card.close(creator: @user)
+
+    assert_difference -> { Card::Closure.count }, -1 do
+      @card.reopen
+    end
+
+    refute @card.closed?
+  end
+end
+```
+
+### Integration Tests
+
+Test full request/response cycles:
+
+```ruby
+class CardsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:david)
+    sign_in @user
+  end
+
+  test "closing a card" do
+    card = cards(:one)
+
+    post card_closure_path(card)
+
+    assert_response :success
+    assert card.reload.closed?
+  end
+
+  test "unauthorized user cannot close card" do
+    sign_in users(:guest)
+    card = cards(:one)
+
+    post card_closure_path(card)
+
+    assert_response :forbidden
+    refute card.reload.closed?
+  end
+end
+```
+
+### System Tests
+
+Browser-based tests using Capybara:
+
+```ruby
+class MessagesTest < ApplicationSystemTestCase
+  test "sending a message" do
+    sign_in users(:david)
+    visit room_path(rooms(:watercooler))
+
+    fill_in "Message", with: "Hello, world!"
+    click_button "Send"
+
+    assert_text "Hello, world!"
+  end
+
+  test "editing own message" do
+    sign_in users(:david)
+    visit room_path(rooms(:watercooler))
+
+    within "#message_#{messages(:greeting).id}" do
+      click_on "Edit"
+    end
+
+    fill_in "Message", with: "Updated message"
+    click_button "Save"
+
+    assert_text "Updated message"
+  end
+
+  test "drag and drop card to new column" do
+    sign_in users(:david)
+    visit board_path(boards(:main))
+
+    card = find("#card_#{cards(:one).id}")
+    target = find("#column_#{columns(:done).id}")
+
+    card.drag_to target
+
+    assert_selector "#column_#{columns(:done).id} #card_#{cards(:one).id}"
+  end
+end
+```
+
+## Advanced Patterns
+
+### Time Testing
+
+Use `travel_to` for deterministic time-dependent assertions:
+
+```ruby
+test "card expires after 30 days" do
+  card = cards(:one)
+
+  travel_to 31.days.from_now do
+    assert card.expired?
+  end
+end
+```
+
+### External API Testing with VCR
+
+Record and replay HTTP interactions:
+
+```ruby
+test "fetches user data from API" do
+  VCR.use_cassette("user_api") do
+    user_data = ExternalApi.fetch_user(123)
+
+    assert_equal "John", user_data[:name]
+  end
+end
+```
+
+### Background Job Testing
+
+Assert job enqueueing and email delivery:
+
+```ruby
+test "closing card enqueues notification job" do
+  card = cards(:one)
+
+  assert_enqueued_with(job: NotifyWatchersJob, args: [card]) do
+    card.close
+  end
+end
+
+test "welcome email is sent on signup" do
+  assert_emails 1 do
+    Identity.create!(email: "new@example.com")
+  end
+end
+```
+
+### Testing Turbo Streams
+
+```ruby
+test "message creation broadcasts to room" do
+  room = rooms(:watercooler)
+
+  assert_turbo_stream_broadcasts [room, :messages] do
+    room.messages.create!(body: "Test", creator: users(:david))
+  end
+end
+```
+
+## Testing Principles
+
+### 1. Test Observable Behavior
+
+Focus on what the code does, not how it does it:
+
+```ruby
+# ❌ Testing implementation
+test "calls notify method on each watcher" do
+  card.expects(:notify).times(3)
+  card.close
+end
+
+# ✅ Testing behavior
+test "watchers receive notifications when card closes" do
+  assert_difference -> { Notification.count }, 3 do
+    card.close
+  end
+end
+```
+
+### 2. Don't Mock Everything
+
+```ruby
+# ❌ Over-mocked test
+test "sending message" do
+  room = mock("room")
+  user = mock("user")
+  message = mock("message")
+
+  room.expects(:messages).returns(stub(create!: message))
+  message.expects(:broadcast_create)
+
+  MessagesController.new.create
+end
+
+# ✅ Test the real thing
+test "sending message" do
+  sign_in users(:david)
+  post room_messages_url(rooms(:watercooler)),
+    params: { message: { body: "Hello" } }
+
+  assert_response :success
+  assert Message.exists?(body: "Hello")
+end
+```
+
+### 3. Tests Ship with Features
+
+Same commit, not TDD-first but together. Neither before (strict TDD) nor after (deferred testing).
+
+### 4. Security Fixes Always Include Regression Tests
+
+Every security fix must include a test that would have caught the vulnerability.
+
+### 5. Integration Tests Validate Complete Workflows
+
+Don't just test individual pieces - test that they work together.
+
+## File Organization
+
+```
+test/
+├── controllers/         # Integration tests for controllers
+├── fixtures/           # YAML fixtures for all models
+├── helpers/            # Helper method tests
+├── integration/        # API integration tests
+├── jobs/               # Background job tests
+├── mailers/            # Mailer tests
+├── models/             # Unit tests for models
+├── system/             # Browser-based system tests
+└── test_helper.rb      # Test configuration
+```
+
+## Test Helper Setup
+
+```ruby
+# test/test_helper.rb
+ENV["RAILS_ENV"] ||= "test"
+require_relative "../config/environment"
+require "rails/test_help"
+
+class ActiveSupport::TestCase
+  fixtures :all
+
+  parallelize(workers: :number_of_processors)
+end
+
+class ActionDispatch::IntegrationTest
+  include SignInHelper
+end
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :selenium, using: :headless_chrome
+end
+```
+
+## Sign In Helper
+
+```ruby
+# test/support/sign_in_helper.rb
+module SignInHelper
+  def sign_in(user)
+    session = user.identity.sessions.create!
+    cookies.signed[:session_id] = session.id
+  end
+end
+```

package/skills/discord-content/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: discord-content
+description: "This skill should be used when creating and posting community content to Discord. Generates brand-consistent posts and posts via webhook after approval."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Discord Content
+
+Create and post brand-consistent community content to Discord. Content is generated from a user-provided topic, validated against the brand guide, and posted via webhook after explicit user approval.
+
+## Prerequisites
+
+Before generating content, verify both prerequisites. If either fails, display the error message and stop.
+
+### 1. Brand Guide
+
+Check if `knowledge-base/marketing/brand-guide.md` exists.
+
+**If missing:**
+> No brand guide found. Run the brand architect agent first to establish brand identity:
+> `Use the soleur:marketing:brand-architect agent to define our brand.`
+
+Stop execution.
+
+### 2. Discord Webhook URL
+
+Check if the `DISCORD_WEBHOOK_URL` environment variable is set.
+
+**If missing:**
+> `DISCORD_WEBHOOK_URL` is not set. To configure:
+>
+> 1. Open Discord server > Server Settings > Integrations > Webhooks
+> 2. Click "New Webhook" and configure the target channel
+> 3. Copy the webhook URL
+> 4. Set the environment variable: `export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."`
+
+Stop execution.
+
+## Content Generation
+
+### Phase 1: Topic Input
+
+Ask the user: "What would you like to post about?"
+
+Accept a freeform topic description. Optionally offer: "Summarize recent git activity?" -- if accepted, run `git log --oneline -20` to gather recent commits and PRs as source material.
+
+### Phase 2: Generate Draft
+
+Read the brand guide sections that inform content generation:
+
+1. Read `## Voice` -- apply brand voice, tone, do's and don'ts
+2. Read `## Channel Notes > ### Discord` -- apply Discord-specific guidelines (if the section exists)
+
+Generate a draft post that:
+
+- Addresses the user's topic
+- Matches the brand voice from `## Voice`
+- Follows Discord channel guidelines from `## Channel Notes`
+- Stays within the 2000-character Discord message limit
+
+### Phase 3: Inline Brand Voice Check
+
+Before presenting the draft to the user, validate it against the brand guide:
+
+1. Check the draft against the `### Do's and Don'ts` section
+2. If any "Don't" patterns are found, revise the draft to remove them
+3. If the draft exceeds 2000 characters, trim it while preserving key messages
+4. Note any adjustments made
+
+### Phase 4: User Approval
+
+Present the final draft to the user with character count displayed. Use the **AskUserQuestion tool** with three options:
+
+- **Accept** -- Post this content to Discord
+- **Edit** -- Provide feedback to revise the draft (return to Phase 2 with feedback)
+- **Reject** -- Discard the draft and exit
+
+### Phase 5: Post to Discord
+
+On acceptance, post the content via webhook:
+
+First get the webhook URL with `printenv DISCORD_WEBHOOK_URL`, then use the literal URL:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\": \"ESCAPED_CONTENT\", \"username\": \"Sol\", \"avatar_url\": \"AVATAR_URL\", \"allowed_mentions\": {\"parse\": []}}" \
+  "<webhook-url>"
+```
+
+Replace `<webhook-url>` with the actual URL from `printenv`.
+
+Set `avatar_url` to the hosted logo URL (e.g., the GitHub-hosted `logo-mark-512.png`). Webhook messages freeze author identity at post time -- these fields ensure consistent branding.
+
+**Content must be properly JSON-escaped** before inserting into the payload. Escape double quotes, backslashes, and newlines.
+
+**Payload format:** Plain `content` field only. No rich embeds in v1.
+
+### Phase 6: Result
+
+**On success (HTTP 2xx):**
+> Posted to Discord successfully.
+
+**On failure (HTTP 4xx/5xx):**
+> Failed to post to Discord (HTTP [status_code]).
+>
+> Draft content (copy-paste manually):
+>
+> ```
+> [full draft content]
+> ```
+
+Display the draft so the user can post it manually. Do not retry automatically.
+
+## Important Guidelines
+
+- All content requires explicit user approval before posting -- no auto-send
+- The 2000-character limit is enforced during generation, not as a post-hoc check
+- Content uses the plain `content` field, not Discord rich embeds
+- JSON-escape all content before inserting into the webhook payload
+- If the brand guide's `## Channel Notes > ### Discord` section is missing, generate content using only the `## Voice` section (no error)
+- If the user selects "Edit", incorporate their feedback and regenerate -- do not present the same draft
+- When posting via webhook, always include `username` and `avatar_url` fields to ensure consistent bot identity -- webhook messages freeze author identity at post time

package/skills/docs-site/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: docs-site
+description: "This skill should be used when scaffolding a Markdown-based documentation site using Eleventy. It generates a complete docs setup with base layout, data files, GitHub Pages deployment workflow, and passthrough copy configuration."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# docs-site Skill
+
+Scaffold a Markdown + Eleventy documentation site with build-time data injection and GitHub Pages deployment.
+
+## Prerequisites
+
+- Node.js 20+
+- A `package.json` in the project root (or willingness to create one)
+
+## Step 1: Gather Project Info
+
+Ask the user:
+
+1. **Project name** -- Used in site title, footer, nav logo
+2. **Site URL** -- For meta tags, sitemap, og:url (e.g., `https://example.com`)
+3. **Author name** -- For blog attribution, structured data, and E-E-A-T signals (e.g., `Jean Deruelle`)
+4. **Docs input directory** -- Where docs source files live (e.g., `docs/`)
+5. **GitHub repository URL** -- For nav link and deployment
+6. **Pages to create** -- Which pages beyond index (e.g., getting-started, changelog, API reference)
+
+## Step 2: Install Dependencies
+
+```bash
+npm install --save-dev @11ty/eleventy
+```
+
+Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:dev": "npx @11ty/eleventy --serve",
+    "docs:build": "npx @11ty/eleventy"
+  }
+}
+```
+
+Ensure `"type": "module"` is set in `package.json` for ESM config.
+
+## Step 3: Create Eleventy Config
+
+Create `eleventy.config.js` at the project root:
+
+```javascript
+const INPUT = "<docs-input-dir>";
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPassthroughCopy({ [`${INPUT}/css`]: "css" });
+  eleventyConfig.addPassthroughCopy({ [`${INPUT}/images`]: "images" });
+  // Add more passthrough copies as needed
+}
+
+export const config = {
+  dir: {
+    input: INPUT,
+    output: "_site",
+    includes: "_includes",
+    data: "_data",
+  },
+  markdownTemplateEngine: "njk",
+  htmlTemplateEngine: "njk",
+  templateFormats: ["md", "njk"],
+};
+```
+
+Add `_site/` to `.gitignore`.
+
+## Step 4: Create Directory Structure
+
+```
+<docs-input-dir>/
+  _data/
+    site.json          # Site metadata (name, url, nav)
+  _includes/
+    base.njk           # Base HTML layout
+  css/
+    style.css          # Minimal starter CSS
+  images/              # Static images
+  index.njk            # Landing page
+  pages/
+    getting-started.md # First content page
+```
+
+### `_data/site.json`
+
+```json
+{
+  "name": "<Project Name>",
+  "url": "<site-url>",
+  "author": {
+    "name": "<Author Name>",
+    "url": "<site-url>"
+  },
+  "nav": [
+    { "label": "Get Started", "url": "pages/getting-started.html" }
+  ]
+}
+```
+
+### `_includes/base.njk`
+
+Create a minimal HTML shell with:
+
+- Head: charset, viewport, description meta, title, CSS link
+- Header: logo linking to index.html, nav from `site.nav`
+- Main: `{{ content | safe }}`
+- Footer: project name, links
+
+Use `page.url` comparison for `aria-current="page"` on nav links.
+
+### `css/style.css`
+
+Provide a minimal starter stylesheet with CSS custom properties for easy theming.
+
+### Content pages
+
+Create `.md` files with YAML frontmatter:
+
+```yaml
+---
+title: Getting Started
+description: "How to get started with <Project Name>"
+layout: base.njk
+permalink: pages/getting-started.html
+---
+```
+
+## Step 5: Data Files (Optional)
+
+If the project has components to catalog at build time, create data files in `_data/`:
+
+```javascript
+// _data/version.js -- reads version from package.json
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export default function () {
+  const pkg = JSON.parse(readFileSync(resolve("package.json"), "utf-8"));
+  return pkg.version;
+}
+```
+
+Data files export a function that returns data available in all templates.
+
+## Step 6: GitHub Pages Workflow
+
+Create `.github/workflows/deploy-docs.yml`:
+
+```yaml
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '<docs-input-dir>/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: npx @11ty/eleventy
+      - uses: actions/configure-pages@v4
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - uses: actions/deploy-pages@v4
+```
+
+## Step 7: Verify
+
+```bash
+npx @11ty/eleventy --serve
+```
+
+Open `http://localhost:8080` and verify:
+
+- All pages render correctly
+- CSS loads
+- Navigation works with `aria-current="page"`
+- Data variables resolve in templates
+
+## Notes
+
+- Nunjucks variables (`{{ var }}`) are NOT resolved inside YAML frontmatter. Use static strings for `description` in frontmatter, and template variables only in the page body.
+- Passthrough copy paths in `addPassthroughCopy()` are relative to the project root, NOT the input directory. Use the mapping format: `{ "source/path": "output/path" }`.
+- Eleventy v3 uses ESM (`export default`) -- do not use CommonJS (`module.exports`).