refactor(plugin)!: restructure plugin architecture for better context management

lambdalisue · lambdalisue · commit 8e495951237a · 2025-12-20T01:30:46.000+09:00
BREAKING CHANGE: Plugin structure completely reorganized

Split monolithic configuration into focused components following
Claude Code plugin best practices for context optimization:

Skills (3 files):
- probitas-setup: CLI installation and project initialization
- probitas-write: Scenario writing (delegates to agent)
- probitas-run: Running and debugging scenarios

Rules (6 files with paths: "**/*.probitas.ts"):
- import: Import statements
- pattern: Export pattern and scenario structure
- assertions: expect() chaining
- mistakes: Common mistakes (casting, null checks, specialized methods)
- best-practices: Step naming, tags, cleanup
- context: Step context (ctx) usage

Agent:
- scenario-writer: Enhanced with template, checklist, and comprehensive
  API reference links for all 13 clients

Commands:
- Updated documentation URLs to point to official docs
- Fixed glob patterns (probitas/ → **/*.probitas.ts)
- Added lint rules exclusion for JSR imports

Why this structure:
- Rules auto-load when editing *.probitas.ts (lazy loading)
- Skills trigger on description keywords (proactive)
- Agent runs in isolated context with full reference material
- Eliminates duplication between components
diff --git a/plugins/probitas/README.md b/plugins/probitas/README.md
@@ -7,12 +7,20 @@ scenario testing framework.
 
 ### Rules
 
-- **conventions** - File structure, naming, and coding conventions (always
-  applied)
+Applied automatically when editing `*.probitas.ts` files:
+
+- **import** - Import statements
+- **pattern** - Export pattern (single/multiple)
+- **assertions** - expect() chaining rules
+- **mistakes** - Common mistakes to avoid
+- **best-practices** - Best practices
+- **context** - Step context (ctx) usage
 
 ### Skills
 
-- **probitas** - Scenario testing knowledge and patterns (on-demand)
+- **probitas-setup** - CLI installation and project setup
+- **probitas-write** - Scenario writing (delegates to agent)
+- **probitas-run** - Running and debugging scenarios
 
 ### Commands
 
@@ -21,12 +29,11 @@ scenario testing framework.
 | `/probitas:init`           | Initialize a Probitas project |
 | `/probitas:run [selector]` | Run scenarios                 |
 | `/probitas:new <type>`     | Generate scenario template    |
-| `/probitas:check`          | Run syntax check              |
+| `/probitas:check`          | Run format, lint, type check  |
 
 ### Agents
 
-- **scenario-writer** - Specialized agent for creating integration test
-  scenarios
+- **scenario-writer** - Create and edit `*.probitas.ts` files
 
 ## Installation
 
diff --git a/plugins/probitas/agents/scenario-writer.md b/plugins/probitas/agents/scenario-writer.md
@@ -1,30 +1,67 @@
 ---
 name: scenario-writer
-description: Create integration test scenarios. Use when user needs Probitas scenarios.
+description: Create and edit *.probitas.ts files. Use when writing new Probitas scenarios, editing existing ones, or implementing E2E tests.
 ---
 
-Expert Probitas scenario writer. Documentation-driven, best practices.
+## Template
+
+```typescript
+import { client, expect, scenario } from "jsr:@probitas/probitas";
+
+export default scenario("Test name", { tags: ["..."] })
+  .resource("http", () =>
+    client.http.createHttpClient({
+      url: Deno.env.get("API_URL") ?? "http://localhost:8080",
+    }))
+  .step("Step name", async (ctx) => {
+    const res = await ctx.resources.http.post("/endpoint", { body: {} });
+    expect(res).toBeOk().toHaveStatus(200);
+    return res.json<{ id: number }>()!;
+  })
+  .build();
+```
 
 ## Workflow
 
-1. **Before**: Fetch docs via WebFetch
-   (https://jsr-probitas.github.io/documents/llms.txt)
-2. **During**: Use `probitas` skill patterns, follow conventions
-3. **After**: Run `/probitas:check`, fix issues
+1. Write scenario following template above
+2. Run `/probitas:check`, fix issues
+3. If unsure, fetch specific API docs from links below
 
 ## Checklist
 
 - [ ] `export default` + `.build()`
 - [ ] Resources via `.resource()`
 - [ ] Setup returns cleanup function
 - [ ] Env vars for URLs
-- [ ] Specific assertions
+- [ ] Chain assertions with `expect()`
 - [ ] Tags for filtering
 - [ ] File: `probitas/{name}.probitas.ts`
 
-## When Uncertain
+## Docs
 
-Fetch specific docs:
+Guides:
 
+- Scenario: https://jsr-probitas.github.io/documents/docs/scenario/index.md
 - Client: https://jsr-probitas.github.io/documents/docs/client/index.md
-- Assertions: https://jsr-probitas.github.io/documents/docs/expect/index.md
+- Expect: https://jsr-probitas.github.io/documents/docs/expect/index.md
+
+API Reference (by client):
+
+- HTTP: https://jsr-probitas.github.io/documents/api/client-http/index.md
+- gRPC: https://jsr-probitas.github.io/documents/api/client-grpc/index.md
+- ConnectRPC: https://jsr-probitas.github.io/documents/api/client-connectrpc/index.md
+- GraphQL: https://jsr-probitas.github.io/documents/api/client-graphql/index.md
+- PostgreSQL: https://jsr-probitas.github.io/documents/api/client-sql-postgres/index.md
+- MySQL: https://jsr-probitas.github.io/documents/api/client-sql-mysql/index.md
+- SQLite: https://jsr-probitas.github.io/documents/api/client-sql-sqlite/index.md
+- DuckDB: https://jsr-probitas.github.io/documents/api/client-sql-duckdb/index.md
+- Redis: https://jsr-probitas.github.io/documents/api/client-redis/index.md
+- MongoDB: https://jsr-probitas.github.io/documents/api/client-mongodb/index.md
+- Deno KV: https://jsr-probitas.github.io/documents/api/client-deno-kv/index.md
+- RabbitMQ: https://jsr-probitas.github.io/documents/api/client-rabbitmq/index.md
+- SQS: https://jsr-probitas.github.io/documents/api/client-sqs/index.md
+
+Core API:
+
+- Scenario: https://jsr-probitas.github.io/documents/api/scenario/index.md
+- Expect: https://jsr-probitas.github.io/documents/api/expect/index.md
diff --git a/plugins/probitas/commands/check.md b/plugins/probitas/commands/check.md
@@ -10,9 +10,9 @@ description: Run format, lint, and type check for scenarios
 4. **Fix** - If issues found, fix them and repeat
 
 ```bash
-deno fmt probitas/
-deno lint --rules-exclude=no-import-prefix,no-unversioned-import probitas/
-deno check probitas/**/*.probitas.ts
+deno fmt **/*.probitas.ts
+deno lint --rules-exclude=no-import-prefix,no-unversioned-import **/*.probitas.ts
+deno check **/*.probitas.ts
 ```
 
 Fix issues iteratively until all pass.
diff --git a/plugins/probitas/commands/init.md b/plugins/probitas/commands/init.md
@@ -8,6 +8,6 @@ ls -la probitas/
 ```
 
 If `probitas` command not found, fetch installation instructions from:
-https://jsr-probitas.github.io/documents/docs/index.md
+https://jsr-probitas.github.io/documents/docs/installation/index.md
 
 Report created files to user.
diff --git a/plugins/probitas/commands/new.md b/plugins/probitas/commands/new.md
@@ -4,11 +4,9 @@ description: Generate scenario template (http, database, grpc, graphql)
 
 ## Workflow
 
-1. Fetch template info from
-   https://jsr-probitas.github.io/documents/docs/scenario/index.md
-2. Generate template based on type argument
-3. Save to `probitas/{name}.probitas.ts`
-4. Run `deno check probitas/{name}.probitas.ts`
+1. Generate template based on type argument
+2. Save to `probitas/{name}.probitas.ts`
+3. Run `deno check **/*.probitas.ts`
 
 ## Templates
 
@@ -45,3 +43,7 @@ export default scenario("Database Test", { tags: ["database"] })
   })
   .build();
 ```
+
+## Docs
+
+https://jsr-probitas.github.io/documents/docs/scenario/index.md
diff --git a/plugins/probitas/commands/run.md b/plugins/probitas/commands/run.md
@@ -20,6 +20,6 @@ probitas run -s user                # Match scenario name
 ```
 
 If `probitas` command not found, fetch installation instructions from:
-https://jsr-probitas.github.io/documents/docs/index.md
+https://jsr-probitas.github.io/documents/docs/installation/index.md
 
 If failures occur, explain cause and suggest fixes.
diff --git a/plugins/probitas/rules/assertions.md b/plugins/probitas/rules/assertions.md
@@ -0,0 +1,21 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Assertions
+
+ALWAYS use `expect()`, ALWAYS chain.
+
+```typescript
+// ❌ WRONG
+if (res.status !== 200) throw new Error("Failed");
+
+// ✅ CORRECT
+expect(res)
+  .toBeOk()
+  .toHaveStatus(200)
+  .toHaveJsonMatching({ id: 1 });
+
+// Negation
+expect(res).not.toHaveStatus(404);
+```
diff --git a/plugins/probitas/rules/best-practices.md b/plugins/probitas/rules/best-practices.md
@@ -0,0 +1,13 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Best Practices
+
+- Descriptive step names ("Create user" not "Step 1")
+- Return data for `ctx.previous`
+- Use tags for filtering (`{ tags: ["api", "slow"] }`)
+- One responsibility per step
+- Use `.setup()` with cleanup for fixtures
+- Register clients as `.resource()` for auto-cleanup
+- Use `toHaveJsonMatching()` / `toHaveDataMatching()` for partial matching
diff --git a/plugins/probitas/rules/context.md b/plugins/probitas/rules/context.md
@@ -0,0 +1,13 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Step Context
+
+Available in `.resource()`, `.setup()`, and `.step()`:
+
+- `ctx.previous` - Previous step's return value
+- `ctx.results` - All previous step results (tuple)
+- `ctx.resources` - Registered resources by name
+- `ctx.store` - Shared Map across steps
+- `ctx.signal` - AbortSignal for cancelable operations
diff --git a/plugins/probitas/rules/conventions.md b/plugins/probitas/rules/conventions.md
diff --git a/plugins/probitas/rules/import.md b/plugins/probitas/rules/import.md
@@ -0,0 +1,10 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Import
+
+```typescript
+import { client, expect, scenario, Skip } from "jsr:@probitas/probitas";
+import { faker, FakeTime, spy, stub } from "jsr:@probitas/probitas";
+```
diff --git a/plugins/probitas/rules/mistakes.md b/plugins/probitas/rules/mistakes.md
@@ -0,0 +1,93 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Common Mistakes
+
+## Missing export default / .build()
+
+```typescript
+// ❌ BAD
+const s = scenario("Test").step(() => {});
+
+// ✅ GOOD
+export default scenario("Test").step(() => {}).build();
+```
+
+## Hardcoded URL
+
+```typescript
+// ❌ BAD
+client.http.createHttpClient({ url: "http://localhost:8080" });
+
+// ✅ GOOD
+client.http.createHttpClient({
+  url: Deno.env.get("API_URL") ?? "http://localhost:8080",
+});
+```
+
+## Step returns nothing
+
+```typescript
+// ❌ BAD - loses data
+.step("Create", async (ctx) => {
+  await ctx.resources.http.post("/users", { body: {} });
+})
+
+// ✅ GOOD - pass to next step
+.step("Create", async (ctx) => {
+  const res = await ctx.resources.http.post("/users", { body: {} });
+  return res.json<{ id: number }>()!;
+})
+```
+
+## Missing cleanup
+
+```typescript
+// ✅ GOOD - setup returns cleanup function
+.setup(async (ctx) => {
+  await ctx.resources.db.query("INSERT...");
+  return async () => {
+    await ctx.resources.db.query("DELETE...");
+  };
+})
+```
+
+## Unnecessary type casting
+
+```typescript
+// ❌ BAD - return is any, cast is redundant
+const data = res.json() as { id: number };
+
+// ✅ GOOD
+const data = res.json(); // any
+
+// ✅ GOOD
+const data = res.json<{ id: number }>();
+```
+
+## Defensive null checks
+
+```typescript
+// ❌ BAD - test code, not production
+const data = res.json<{ id: number }>();
+if (data) {
+  expect(data.id).toBe(1);
+}
+
+// ✅ GOOD - use ! or as
+const data = res.json<{ id: number }>()!;
+expect(data.id).toBe(1);
+```
+
+## Missing specialized methods
+
+```typescript
+// ❌ BAD - unclear error on failure
+if (res.status !== 200) throw new Error("Failed");
+expect(res.headers.get("content-type")).toContain("json");
+
+// ✅ GOOD - use specialized methods for clear errors
+expect(res).toHaveStatus(200);
+expect(res).toHaveHeadersPropertyContaining("content-type", "json");
+```
diff --git a/plugins/probitas/rules/pattern.md b/plugins/probitas/rules/pattern.md
@@ -0,0 +1,24 @@
+---
+paths: "**/*.probitas.ts"
+---
+
+# Probitas Scenario Structure
+
+**Scenario** = sequential steps that depend on each other (`ctx.previous`).
+**Scenario file** = grouping of related scenarios.
+
+- Steps sharing context → same scenario
+- Independent steps → separate scenarios
+
+```typescript
+// Single scenario in file
+export default scenario("Test").step(...).build();
+
+// Multiple scenarios in file
+export default [
+  scenario("Test A").step(...).build(),
+  scenario("Test B").step(...).build(),
+];
+```
+
+Always end with `.build()`.
diff --git a/plugins/probitas/rules/scenario-writing.md b/plugins/probitas/rules/scenario-writing.md
diff --git a/plugins/probitas/skills/probitas-run/SKILL.md b/plugins/probitas/skills/probitas-run/SKILL.md
diff --git a/plugins/probitas/skills/probitas-setup/SKILL.md b/plugins/probitas/skills/probitas-setup/SKILL.md
diff --git a/plugins/probitas/skills/probitas-write/SKILL.md b/plugins/probitas/skills/probitas-write/SKILL.md
diff --git a/plugins/probitas/skills/probitas/SKILL.md b/plugins/probitas/skills/probitas/SKILL.md
