@iceinvein/agent-skills 0.1.37 → 0.1.39

package/skills/magpie/scripts/__tests__/skill-lint.test.ts

@@ -2,10 +2,35 @@ import { expect, test } from 'bun:test'
 import { readFile } from 'node:fs/promises'
 
 const SKILL = new URL('../../SKILL.md', import.meta.url).pathname
+const SKILL_JSON = new URL('../../skill.json', import.meta.url).pathname
+const ref = (name: string) => new URL(`../../references/${name}`, import.meta.url).pathname
 const FOCUSES = ['security', 'bugs', 'performance', 'code-smells', 'architecture'] as const
 
-test('SKILL.md has a specialist block for every focus', async () => {
+test('every references/ path SKILL.md cites exists on disk', async () => {
   const text = await readFile(SKILL, 'utf8')
+  const cited = [...text.matchAll(/references\/[a-z0-9-]+\.md/g)].map((m) => m[0])
+  expect(cited.length).toBeGreaterThan(0)
+  for (const rel of new Set(cited)) {
+    const body = await readFile(new URL(`../../${rel}`, import.meta.url).pathname, 'utf8')
+    expect(body.length).toBeGreaterThan(0)
+  }
+})
+
+test('references/ ships in the install bundle', async () => {
+  // resolveBundlePaths silently drops include entries that match nothing, so a
+  // missing entry here would install a SKILL.md whose prompts are all 404s.
+  const manifest = JSON.parse(await readFile(SKILL_JSON, 'utf8')) as {
+    bundle: { include: string[] }
+  }
+  const covers = (p: string) =>
+    manifest.bundle.include.some((inc) => inc === p || p.startsWith(`${inc}/`))
+  for (const name of ['specialists.md', 'critic.md', 'peer-review.md']) {
+    expect(covers(`references/${name}`)).toBe(true)
+  }
+})
+
+test('references/specialists.md has a block for every focus', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
   for (const focus of FOCUSES) {
     const tag = `magpie-specialist-${focus}`
     const fence = `\`\`\`${tag}`
@@ -13,23 +38,69 @@ test('SKILL.md has a specialist block for every focus', async () => {
     const start = text.indexOf(fence)
     const end = text.indexOf('```', start + tag.length + 3)
     const block = text.slice(start, end)
-    expect(block).toContain('orchestrator')
+    expect(block).toContain('Output Contract')
     expect(block).toContain(focus)
   }
 })
 
-test('SKILL.md §4 specifies the findings file path', async () => {
-  const text = await readFile(SKILL, 'utf8')
-  // The file-write instruction lives once, in the orchestrator template before §5.
-  const orchestrator = text.slice(0, text.indexOf('```magpie-specialist-'))
-  expect(orchestrator).toMatch(/findings\/<focus>\.json/)
-  expect(orchestrator).toMatch(/Write findings to/i)
+test('references/specialists.md carries the output contract next to the blocks', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  // The contract has to travel with the prompts: the orchestrator assembles
+  // both into one subagent prompt from this single file.
+  const contract = text.slice(0, text.indexOf('```magpie-specialist-'))
+  expect(contract).toContain('## Output Contract')
+  expect(contract).toMatch(/findings\/<focus>\.json/)
+  expect(contract).toMatch(/Write findings to/i)
+  // Severity, impact, likelihood, confidence, action enums must all be listed.
+  expect(contract).toMatch(/"blocker".*"high".*"medium".*"low"/)
+  expect(contract).toMatch(/"critical".*"high".*"medium".*"low"/)
+  expect(contract).toMatch(/"likely".*"possible".*"edge-case".*"unknown"/)
+  expect(contract).toMatch(/"must-fix".*"should-fix".*"consider".*"optional"/)
+  expect(contract).toMatch(/"impact"[\s\S]*"likelihood"[\s\S]*"confidence"[\s\S]*"action"/)
+  expect(contract).toMatch(/"body"[\s\S]*"startLine"[\s\S]*"endLine"/)
+  // Anti-patterns flagged explicitly so subagents don't repeat the JSON-shape mistakes.
+  expect(contract).toMatch(/NOT "lines"/)
+  expect(contract).toMatch(/NOT "recommendation"/)
 })
 
-test('SKILL.md has the critic and peer-review blocks', async () => {
-  const text = await readFile(SKILL, 'utf8')
+test('references/critic.md holds the rubric and both placeholders', async () => {
+  const text = await readFile(ref('critic.md'), 'utf8')
   expect(text).toContain('```magpie-critic')
+  expect(text).toContain('<<DEDUPED_FINDINGS_COMPACT>>')
+  expect(text).toContain('<<DIFF_EXCERPT>>')
+  expect(text).toContain('review-critic')
+})
+
+test('references/peer-review.md holds the prompt and the Claude preamble', async () => {
+  const text = await readFile(ref('peer-review.md'), 'utf8')
   expect(text).toContain('```magpie-peer-review')
+  expect(text).toContain('```magpie-peer-review-claude-preamble')
+  expect(text).toContain('review-peer-review')
+  for (const ph of ['<<PRIMARY_PROVIDER>>', '<<PEER_PROVIDER>>', '<<KEPT_FINDINGS_COMPACT>>']) {
+    expect(text).toContain(ph)
+  }
+})
+
+test('SKILL.md sends each stage to the reference file it needs', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const section = (heading: string) => {
+    const start = text.indexOf(heading)
+    expect(start).toBeGreaterThan(-1)
+    const next = text.indexOf('\n### ', start + heading.length)
+    return text.slice(start, next === -1 ? undefined : next)
+  }
+  expect(section('### 3. Specialists')).toContain('references/specialists.md')
+  expect(section('### 5. Critic')).toContain('references/critic.md')
+  expect(section('### 6. Peer review')).toContain('references/peer-review.md')
+})
+
+test('SKILL.md no longer inlines the prompt bodies it moved out', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  for (const tag of ['magpie-specialist-', 'magpie-critic', 'magpie-peer-review']) {
+    expect(text).not.toContain(`\`\`\`${tag}`)
+  }
+  // The walkthrough is the always-read part; keep it small enough to be cheap.
+  expect(text.split(/\s+/).length).toBeLessThan(2600)
 })
 
 test('styles.css declares a prefers-color-scheme:dark block that overrides core tokens', async () => {
@@ -104,25 +175,42 @@ test('severity chips and submit button no longer hardcode `color: white` (must f
   }
 })
 
-test('SKILL.md §4 inlines the full specialist schema with enum vocabularies', async () => {
+test('SKILL.md checks for a resumable run before minting a new run id', async () => {
   const text = await readFile(SKILL, 'utf8')
-  // The schema block sits inside the specialist orchestrator template (§4),
-  // before the specialist blocks begin (the first `magpie-specialist-` tag).
-  const schemaCutoff = text.indexOf('```magpie-specialist-')
-  expect(schemaCutoff).toBeGreaterThan(-1)
-  const orchestrator = text.slice(0, schemaCutoff)
-  // Severity, impact, likelihood, confidence, action enums must all be listed.
-  expect(orchestrator).toMatch(/"blocker".*"high".*"medium".*"low"/)
-  expect(orchestrator).toMatch(/"critical".*"high".*"medium".*"low"/)
-  expect(orchestrator).toMatch(/"likely".*"possible".*"edge-case".*"unknown"/)
-  expect(orchestrator).toMatch(/"must-fix".*"should-fix".*"consider".*"optional"/)
-  // The risk field must be documented as an object with the four required keys.
-  expect(orchestrator).toMatch(/"impact"[\s\S]*"likelihood"[\s\S]*"confidence"[\s\S]*"action"/)
-  // suggestion shape: body/startLine/endLine.
-  expect(orchestrator).toMatch(/"body"[\s\S]*"startLine"[\s\S]*"endLine"/)
-  // Anti-patterns flagged explicitly so subagents don't repeat the JSON-shape mistakes.
-  expect(orchestrator).toMatch(/NOT "lines"/)
-  expect(orchestrator).toMatch(/NOT "recommendation"/)
+  // §0 always computed a fresh `pr-<n>-<epoch>` id, so the resume section
+  // (which keyed off that brand-new directory) could never fire.
+  const setupSection = text.slice(0, text.indexOf('### 1. Setup'))
+  expect(setupSection).toContain('magpie --list-runs')
+  expect(setupSection).toMatch(/active/i)
+})
+
+test('SKILL.md does not gate resume on state/server-info', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('## Resuming a crashed run')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('## Aborting', start))
+  // server-info is deleted when the server idles out, so a resumable run
+  // fails that check. log.jsonl is the durable signal.
+  expect(section).toContain('log.jsonl')
+  expect(section).not.toMatch(/if .*server-info.* exists/i)
+  // Resuming must restart the server; the old one is gone.
+  expect(section).toContain('magpie serve')
+  // `context` is a no-op stage: say so, or the agent stalls on it.
+  expect(section).toContain('context')
+})
+
+test('SKILL.md names the report buttons that actually exist', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const actionBar = await readFile(
+    new URL('../render-action-bar.ts', import.meta.url).pathname,
+    'utf8',
+  )
+  for (const label of ['Post Selected', 'Post Recommended']) {
+    expect(actionBar).toContain(label)
+    expect(text).toContain(label)
+  }
+  // The old label was never rendered anywhere.
+  expect(text).not.toContain('Post to PR')
 })
 
 test('SKILL.md has the stage walkthrough', async () => {

package/skills/magpie/scripts/__tests__/status-cmd.test.ts

@@ -31,6 +31,19 @@ test('empty log reports nothing completed', async () => {
   expect(result.next).toBe('setup')
 })
 
+test('a skipped stage advances the resume pointer past it', async () => {
+  // `context` has no work in the pipeline; SKILL.md tells the orchestrator to
+  // log it as skipped. If `skipped` did not advance the pointer, a resume
+  // would be sent back to a stage that has no step to run.
+  await writeFile(
+    join(runDir, 'log.jsonl'),
+    `${JSON.stringify({ stage: 'setup', status: 'done' })}\n${JSON.stringify({ stage: 'context', status: 'skipped' })}\n`,
+  )
+  const result = await runStatus(runDir)
+  expect(result.lastCompleted).toBe('context')
+  expect(result.next).toBe('specialists')
+})
+
 test('error stage halts progression', async () => {
   await writeFile(
     join(runDir, 'log.jsonl'),

package/skills/magpie/scripts/helper.js

@@ -352,6 +352,23 @@
     }
   }
 
+  function isSelected(id) {
+    return findCheckboxes(id).some((cb) => cb.checked && !cb.disabled)
+  }
+
+  // Assigning `cb.checked` in script fires no change event, so any programmatic
+  // selection has to emit its own /events record. `state/events` is the only
+  // channel the orchestrator can read when the user types `post` in the
+  // terminal instead of using the in-page buttons; a silent set drops the
+  // finding from that post.
+  function setCheckedAndNotify(id, checked) {
+    const before = isSelected(id)
+    setChecked(id, checked)
+    const after = isSelected(id)
+    if (after === before) return
+    post({ type: after ? 'select' : 'deselect', findingId: id, timestamp: Date.now() })
+  }
+
   // ---------------------------------------------------------------------------
   // Bulk selection
   // ---------------------------------------------------------------------------
@@ -367,8 +384,8 @@
       if (el.getAttribute('data-posted') === 'true') continue
       ids.add(el.getAttribute('data-finding-id'))
     }
-    for (const id of ids) setChecked(id, true)
-    updateSelectedCount()
+    for (const id of ids) setCheckedAndNotify(id, true)
+    recountSelected()
   }
 
   function handleSelectRecommended() {
@@ -378,8 +395,8 @@
       if (el.getAttribute('data-posted') === 'true') continue
       ids.add(el.getAttribute('data-finding-id'))
     }
-    for (const id of ids) setChecked(id, true)
-    updateSelectedCount()
+    for (const id of ids) setCheckedAndNotify(id, true)
+    recountSelected()
   }
 
   // ---------------------------------------------------------------------------
@@ -399,14 +416,8 @@
     if (cbs.length === 0) return
     const cb = cbs[0]
     if (cb.disabled) return
-    const next = !cb.checked
-    setChecked(id, next)
-    post({
-      type: next ? 'select' : 'deselect',
-      findingId: id,
-      timestamp: Date.now(),
-    })
-    updateSelectedCount()
+    setCheckedAndNotify(id, !cb.checked)
+    recountSelected()
   }
 
   // ---------------------------------------------------------------------------
@@ -535,7 +546,7 @@
         if (cb.disabled) continue
         cb.checked = target.checked
       }
-      updateSelectedCount()
+      recountSelected()
       post({
         type: target.checked ? 'select' : 'deselect',
         findingId: id,

package/skills/magpie/scripts/status-cmd.ts

@@ -13,6 +13,12 @@ const ORDER = [
 ] as const
 
 export type StatusResult = {
+  /**
+   * Highest stage the log says is behind us. A stage logged `skipped` counts:
+   * `context` has no work in the pipeline and is always logged that way, so
+   * treating it as unfinished would send a resume back to a stage that has no
+   * step to run.
+   */
   lastCompleted: (typeof ORDER)[number] | null
   next: (typeof ORDER)[number] | 'cleanup'
   error: string | null
@@ -35,7 +41,10 @@ export async function runStatus(runDir: string): Promise<StatusResult> {
       error = stage
       break
     }
-    if (status === 'done' && (ORDER as readonly string[]).includes(stage)) {
+    if (
+      (status === 'done' || status === 'skipped') &&
+      (ORDER as readonly string[]).includes(stage)
+    ) {
       lastCompleted = stage as StatusResult['lastCompleted']
     }
   }

package/skills/magpie/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via codex exec (falling back to a Claude second opinion when codex is unavailable), and serves an interactive HTML report for selecting findings to post via gh. Bundles a Bun CLI installed onto PATH via the skill's postinstall step. Use when the user asks to review a GitHub pull request.",
   "author": "iceinvein",
   "type": "prompt",
@@ -13,6 +13,7 @@
   "bundle": {
     "include": [
       "bin",
+      "references",
       "scripts",
       "templates",
       "fixtures/example-pr",

package/skills/module-secret-auditor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: module-secret-auditor
-description: Use when creating new files, directories, or modules, when reviewing project structure, when a change ripples across 3+ directories, or when the user asks "where should this code live?" or "how should I structure this?". Trigger on structural decisions and reorganizations.
+description: Use when creating new modules or directories, drawing or questioning module boundaries, when a change ripples across 3+ directories, or when the user asks "where should this code live?" or "how should I structure this?". Trigger on structural decisions and reorganizations. NOT for a module doing too many unrelated things (cohesion-analyzer), domain-language boundaries (bounded-context-auditor), naming conventions, code style, or adding code to existing well-bounded modules.
 ---
 
 # Module Secret Auditor
@@ -69,17 +69,20 @@ When proposing structure, organize around change-reasons, not around nouns or te
 
 Instead of:
 ```
-models/user.ts
-services/userService.ts
+models/user.ts          — user fields for every feature; changed by all of them
+services/userService.ts — session logic + notification prefs + billing address in one file
 controllers/userController.ts
 repositories/userRepository.ts
 ```
 
-Propose:
+Propose (same code, re-homed by which decision changes it):
 ```
 auth/               — secret: how identity is verified and sessions are managed
-pricing/            — secret: how costs are calculated and discounts applied
+                      (absorbs the session/token logic from userService + userController)
 notifications/      — secret: how and when users are notified, via which channels
+                      (absorbs the notification-preference logic from userService)
+billing/            — secret: how billing details are stored and validated
+                      (absorbs the billing fields from user.ts + userRepository)
 ```
 
 Each directory answers: **"If this decision changes, only this directory is affected."**

package/skills/module-secret-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "module-secret-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Parnas-inspired information hiding analysis: module boundaries drawn by change-reason, not by noun or technical layer",
   "author": "iceinvein",
   "type": "prompt",

package/skills/port-adapter-auditor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: port-adapter-auditor
-description: Use when business logic is tangled with database queries, HTTP handling, or third-party SDK calls, when testing a feature requires standing up real infrastructure, or when swapping an infrastructure dependency would require rewriting business logic. Trigger on "I can't test this without a database", "swapping the email provider means rewriting half the service", or when reviewing boundaries between core and infrastructure. NOT for dependency direction between layers, internal module structure within the core, or API contract design.
+description: Use when business logic is tangled with database queries, HTTP handling, or third-party SDK calls, when testing a feature requires standing up real infrastructure, or when swapping an infrastructure dependency would mean rewriting business logic. Trigger on "I can't test this without a database" or "swapping the email provider means rewriting half the service". NOT for dependency direction between layers (dependency-direction-auditor), internal core structure, or API contract design.
 ---
 
 # Port-Adapter Auditor
@@ -288,7 +288,7 @@ Decision engine. The agent prioritizes driven ports (outbound) first because the
 
 **Adapters can depend on libraries; ports cannot.** An adapter can import Stripe SDK, ORM libraries, HTTP frameworks. A port cannot. Ports are library-agnostic.
 
-**Beware ports that mirror adapters.** If your port looks exactly like your adapter's public interface, the port hasn't abstracted anything. It's just a pass-through. The port should translate between domain language and adapter language.
+**Beware ports that mirror adapters.** If your port looks exactly like your adapter's public interface, the port hasn't abstracted anything. It's just a pass-through. The port should be expressed in domain terms so the adapter has something to translate; a port that mirrors the SDK's surface has abstracted nothing.
 
 ## Common Mistakes
 
@@ -298,7 +298,7 @@ Decision engine. The agent prioritizes driven ports (outbound) first because the
 | Port returns infrastructure types | `OrderRepository.getById()` returns an ORM entity. Should return a domain Order. Adapter translates. |
 | Adapter does business logic | Business logic belongs in core. Adapter translates and delegates. If you find logic in an adapter, move it to core. |
 | One giant service (no ports) | Even monoliths need internal hexagons. Define ports between core and persistence, core and messaging, etc. |
-| Testing adapters instead of core | Don't write tests for adapters (they test the library). Write tests for core with mock adapters. Adapter tests are integration tests, not unit tests. |
+| Testing adapters instead of core | Don't unit-test adapters with mocks (that just tests the library). Write unit tests for core with mock adapters; cover adapters with integration tests against the real dependency. |
 | Ports for internal collaboration | Ports are for external systems (database, API, messaging). Internal communication between core modules uses dependency injection, not ports. |
 | Circular imports | Core imports adapter to construct it (bad). Use a composition root outside core to wire dependencies. Core only imports ports. |
 

package/skills/port-adapter-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "port-adapter-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Cockburn-inspired hexagonal architecture analysis: identify ports and adapters, classify boundary health, ensure core testability and swappability",
   "author": "iceinvein",
   "type": "prompt",

package/skills/rams-design-audit/SKILL.md

@@ -18,7 +18,7 @@ A design evaluation framework based on Dieter Rams' *Ten Principles for Good Des
 - When decorative elements (gradients, shadows, borders, icons) are present
 - Evaluating whether a redesign actually improved or just rearranged
 
-**Not for:** Functional logic review, accessibility audits (WCAG compliance), performance optimization, or backend architecture. This skill evaluates *visual design quality*, not correctness.
+**Not for:** Functional logic review, accessibility audits (WCAG compliance), performance optimization, or backend architecture. This skill evaluates *visual design quality*, not correctness. For option overload and memory demands use `cognitive-load-auditor`; for spacing and visual grouping use `gestalt-reviewer` — the three compose on a full UI review.
 
 ## The Process
 
@@ -39,7 +39,7 @@ Apply this ruthlessly to:
 
 ### 2. Evaluate Against Rams' Principles
 
-Score the interface against the principles most relevant to digital UI:
+Evaluate the interface against the principles most relevant to digital UI (a pass/fail-with-evidence judgment per principle; there is no numeric score):
 
 **Is it innovative?**
 - Does the design solve the interaction problem in a way that serves the user, or does it follow a template without questioning whether the template fits?
@@ -112,6 +112,8 @@ RAMS AUDIT: User settings page
 
 Decision engine. After generating UI code, the agent runs the Rams audit on its own output. The audit identifies specific elements to remove and states to add. The human sees the audit alongside the component and can override any cut.
 
+**Acquiring the UI when auditing something the agent didn't just write:** prefer a rendered view (screenshot the user provides, or a browser/screenshot tool if one is available); otherwise audit the component source and stylesheets directly and say which mode the audit ran in (source-only audits can judge decoration, states, and element count, but not rendered visual weight).
+
 When the human has explicitly requested a visual style that conflicts with Rams (e.g., "make it more playful," "add some personality"), the agent acknowledges the tension and adapts the audit to evaluate within the requested style — Rams doesn't mandate austerity, but even playful design should be intentional, not random.
 
 ## Anti-Patterns

package/skills/rams-design-audit/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "rams-design-audit",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Dieter Rams-inspired design audit: every visual element must earn its presence, less but better, clarity through restraint",
   "author": "iceinvein",
   "type": "prompt",

package/skills/seam-finder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seam-finder
-description: Use when modifying existing code the agent didn't write, when the agent's instinct is to rewrite or heavily refactor, when adding tests to untested code, or when working in a codebase with minimal coverage. Trigger on "change this behavior", "add a feature to this", or any modification of legacy or unfamiliar code. NOT for greenfield code or code the agent just wrote in this session.
+description: Use when changing code that has minimal or no test coverage, when the agent's instinct is to rewrite or heavily refactor unfamiliar code, or when adding tests to untested code. Trigger on "carefully change this legacy code", "this has no tests", or modifications where breakage would be hard to detect. NOT for greenfield code, code the agent just wrote in this session, or well-tested code where the suite catches regressions.
 ---
 
 # Seam Finder
@@ -30,7 +30,7 @@ Before modifying existing code, survey the available seams:
 - Look for: constructor parameters, function arguments that accept interfaces, injected services, callback parameters, strategy patterns already in place
 - This is the most common seam in object-oriented code. If a dependency is passed in, you can substitute it.
 
-**Preprocessing seam** — Can the inputs be transformed before they reach this code?
+**Input seam** (an adaptation of Feathers' preprocessing seam, which in the book is the build-time preprocessor; the modern equivalent is transforming inputs) — Can the inputs be transformed before they reach this code?
 - Look for: middleware chains, interceptors, data transformation layers, event handlers, input normalization steps
 - The code doesn't change — its inputs do. This is safe because the original code path is untouched.
 

package/skills/seam-finder/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "seam-finder",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Feathers-inspired legacy code modification: find seams, make minimal incisions, preserve existing behavior",
   "author": "iceinvein",
   "type": "prompt",

package/skills/simplicity-razor/SKILL.md

@@ -136,11 +136,11 @@ SIMPLICITY: Using Redux + Redux Toolkit + RTK Query for app state
 
 | Term | Meaning | Example |
 |------|---------|---------|
-| **Simple** | Not interleaved; one braid | A pure function: data in, data out |
+| **Simple** | Not interleaved; one strand, one fold | A pure function: data in, data out |
 | **Easy** | Near at hand; familiar | An ORM with convention-over-configuration |
-| **Complex** | Interleaved; multiple braids | A function that fetches, caches, transforms, and logs |
-| **Complecting** | The act of braiding together | Adding "just one more concern" to an existing module |
-| **Decomplecting** | The act of separating braids | Splitting a god module into composable parts |
+| **Complex** | Interleaved; strands braided together | A function that fetches, caches, transforms, and logs |
+| **Complecting** | The act of braiding strands together | Adding "just one more concern" to an existing module |
+| **Decomplecting** | The act of separating strands | Splitting a god module into composable parts |
 | **Compose** | Combining simple things | Piping focused functions together |
 | **Artifact** | What you build | Code, modules, services |
 | **Construct** | Tools you use to build | Languages, libraries, patterns |

package/skills/simplicity-razor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "simplicity-razor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Hickey-inspired simplicity analysis: simple vs easy, complecting detection, strand decomposition",
   "author": "iceinvein",
   "type": "prompt",

package/skills/temporal-coupling-detector/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: temporal-coupling-detector
-description: Use when code breaks because functions were called in the wrong order, when objects must be "initialized" before use but nothing prevents using them uninitialized, when setup/teardown sequences exist and forgetting a step causes silent corruption, or when parallelizing sequential code causes mysterious failures. Trigger on "why does this work in the test but fail in production?", "it worked until we changed the call order", or when reviewing multi-step object setup. NOT for intentional pipelines with type-enforced ordering, framework lifecycle hooks managed by the framework, or database transactions.
+description: Use when code breaks because functions were called in the wrong order, when objects must be "initialized" but nothing prevents using them uninitialized, or when parallelizing sequential code causes mysterious failures. Trigger on "works in the test, fails in production", "it worked until we changed the call order", or when reviewing multi-step object setup. NOT for pipelines with type-enforced ordering, framework-managed lifecycle hooks, or database transactions.
 ---
 
 # Temporal Coupling Detector
 
-One of the most insidious forms of coupling — ordering dependencies required but invisible. If `init()` before `process()` is required but nothing enforces it, every caller must just know. The cost isn't immediately obvious: a test passes because the setup happens to occur in the right order. Code works in development, fails in production because initialization runs on a different thread. A refactor parallelizes sequential operations and introduces a race condition no one saw. Fowler and Beck call this a code smell; Kent Beck recommends encoding ordering into the type system so it cannot be violated.
+One of the most insidious forms of coupling — ordering dependencies required but invisible. If `init()` before `process()` is required but nothing enforces it, every caller must just know. The cost isn't immediately obvious: a test passes because the setup happens to occur in the right order. Code works in development, fails in production because initialization runs on a different thread. A refactor parallelizes sequential operations and introduces a race condition no one saw. Hunt and Thomas named temporal coupling in *The Pragmatic Programmer*; Mark Seemann's design-smell treatment popularized the fix this skill teaches: encode the ordering into the type system so it cannot be violated.
 
 **Core principle:** If code must execute in a specific order, that ordering must be enforced by the design — through types, parameters, or API structure — not by documentation or convention. Convention fails at scale. Types prevent failure.
 

package/skills/temporal-coupling-detector/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "temporal-coupling-detector",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Hidden ordering dependency analysis: detect two-phase init, method order dependencies, invisible preconditions, and resource lifecycle violations; fix with types, parameters, and factory patterns",
   "author": "iceinvein",
   "type": "prompt",

package/skills/terse/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: terse
 description: >
-  Professional output compression. Cuts ~20-30% of output tokens while keeping proper grammar,
-  readable prose, and semantic accuracy. Three intensity levels: clean, tight (default), sharp.
-  Always-on from session start. Switch with /terse clean|tight|sharp.
-  Off with "stop terse" or "normal mode".
+  Use when the user invokes /terse or asks for compressed, low-token output.
+  Professional output compression: cuts ~20-30% of output tokens while keeping proper
+  grammar, readable prose, and semantic accuracy. Three intensity levels: clean, tight
+  (default), sharp. Once active it applies to every response until "stop terse" or
+  "normal mode". Installed with global activation (SessionStart hook) it is on from
+  session start; with the default session install it activates when invoked.
 argument-hint: "[clean|tight|sharp]"
 ---
 
@@ -23,7 +25,7 @@ Terse compresses HOW the answer is delivered. It must never change WHAT the answ
 
 ACTIVE EVERY RESPONSE. No filler drift after many turns. Still active if unsure. Off only: "stop terse" / "normal mode".
 
-Active level: **$ARGUMENTS[0]** (default to **tight** if no argument provided). Switch anytime: `/terse clean|tight|sharp`.
+Active level: **$1** (default to **tight** if no argument provided). Switch anytime: `/terse clean|tight|sharp`.
 
 ## What to Eliminate
 
@@ -83,7 +85,9 @@ If context is needed between tool calls, state the *finding* or *decision*, not
 
 These add no information. Remove on sight regardless of level:
 
-just, really, basically, actually, simply, essentially, honestly, certainly, definitely, sure, of course, happy to, absolutely, great question, that's a great point, as mentioned, it's worth noting that, it should be noted, in order to (use "to"), as well as (use "and"), due to the fact that (use "because"), at this point in time (use "now"), utilize (use "use"), demonstrate (use "show"), implement a solution for (use "fix"), investigate (use "check")
+just, really, basically, actually, simply, essentially, honestly, certainly, definitely, sure, of course, happy to, absolutely, great question, that's a great point, as mentioned, it's worth noting that, it should be noted
+
+(Word swaps like utilize→use or in order to→to are `tight`-level substitutions, listed under that level; `clean` keeps natural word choice and only drops the pure filler above.)
 
 ## Intensity Levels
 
@@ -102,6 +106,7 @@ Everything in `clean`, plus shorter synonyms, shorter sentences, and targeted cu
 
 Word cuts:
 - Shorter synonyms: big not extensive, fix not implement, use not utilize, show not demonstrate, check not investigate, need not requirement, start not initialize, end not terminate, send not transmit
+- Shorter phrases: "to" not "in order to", "and" not "as well as", "because" not "due to the fact that", "now" not "at this point in time", "fix" not "implement a solution for"
 - Strip transition phrases on sight: "however", "additionally", "furthermore", "moreover", "that said", "in other words", "it's also worth mentioning", "on the other hand", "as a result", "with that in mind". Just start the next sentence.
 - Replace "this means that" with a dash or colon. Replace "the reason is that" with "because".
 - One idea per sentence. Split compound sentences.
@@ -110,7 +115,7 @@ Content cuts:
 - Direct answer first, then explanation if needed.
 - One example per point. Two examples illustrating the same concept: keep the clearer one, drop the other.
 - If the answer would work without the last paragraph, drop the last paragraph.
-- Do not restructure or add formatting that wasn't in the uncompressed answer. Only cut.
+- Do not restructure or add formatting that wasn't in the uncompressed answer. Only cut. (This rule is `tight`-specific; `sharp` explicitly adds structural compression below.)
 
 ### `sharp`
 

package/skills/terse/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "terse",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Professional output compression. Cuts ~20-30% of output tokens with proper grammar and semantic accuracy. Three levels: clean, tight, sharp.",
   "author": "iceinvein",
   "type": "prompt",

package/skills/type-driven-designer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: type-driven-designer
-description: Use when primitive types (string, number, boolean) represent domain concepts, when nullable fields have ambiguous meaning, when invalid combinations of fields are structurally possible but logically impossible, or when validation happens far from construction. Trigger on "why is this email field just a string?", "how can status be 'shipped' with no tracking number?", or when reviewing domain model types. NOT for performance-critical inner loops where type wrappers add overhead, dynamic/untyped languages, or API boundary serialization shapes.
+description: Use when primitives (string, number, boolean) represent domain concepts, when nullable fields have ambiguous meaning, when invalid field combinations are structurally possible, or when validation happens far from construction. Trigger on "why is this email just a string?", "how can status be 'shipped' with no tracking number?", or when reviewing domain model types. Works in any language with a type layer (TypeScript, Rust, Python + Pydantic). NOT for hot inner loops or API wire formats.
 ---
 
 # Type-Driven Designer
@@ -160,13 +160,13 @@ type PaymentStatus =
   | { status: "completed"; amount: number; transactionId: string; completedAt: Date }
   | { status: "failed"; amount: number; reason: string; failedAt: Date };
 
-function processPayment(payment: PaymentStatus): PaymentStatus {
-  if (payment.status === "pending") {
-    // Only pending payments can be processed
-    return { status: "processing", amount: payment.amount, gatewayId: "..." };
-  }
-  // Can't process already-completed or failed payments — type system enforces it
-  throw new Error(`Cannot process ${payment.status} payment`);
+type PendingPayment = Extract<PaymentStatus, { status: "pending" }>;
+type ProcessingPayment = Extract<PaymentStatus, { status: "processing" }>;
+
+// Accepts ONLY pending payments — passing a completed or failed payment
+// is a compile error, not a runtime throw. The type system enforces it.
+function processPayment(payment: PendingPayment): ProcessingPayment {
+  return { status: "processing", amount: payment.amount, gatewayId: "..." };
 }
 ```
 

package/skills/type-driven-designer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "type-driven-designer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Wlaschin & Minsky-inspired type design: make illegal states unrepresentable through branded types, discriminated unions, and domain-encoded constraints",
   "author": "iceinvein",
   "type": "prompt",