@softspark/ai-toolkit 2.7.1 → 2.7.3

package/CHANGELOG.md

@@ -7,6 +7,25 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.7.3 — Regenerate llms after Medplum Merge (2026-04-17)
+
+### Fixed
+- **`llms.txt` + `llms-full.txt` stale after PR #7 (Medplum/FHIR rules)** — contributor did not re-run `npm run generate:all` before merge, so the machine-readable catalogs did not list `kb/reference/medplum-docs-map.md`, and `kb/reference/language-rules.md` still advertised `13 languages / 68 rule files` instead of `14 languages / 73 rule files`. Validator passes regardless (it does not diff generated text), so the drift slipped past CI. Regenerated from source; added Medplum row to the languages table.
+
+---
+
+## v2.7.2 — Doc & Model-ID Consistency (2026-04-17)
+
+### Changed
+- **Centralized Claude model IDs** — introduced `DEFAULT_CLAUDE_MODELS` dict in `scripts/_common.py` (single source of truth: `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`). `scripts/generate_aider_conf.py` now imports the constant instead of hardcoding `claude-sonnet-4-6`. Next Anthropic model bump touches one file. Agent frontmatter aliases (`opus`/`sonnet`/`haiku`) stay version-free and are resolved at runtime.
+- **`app/agents/ai-engineer.md`** now points to the `model-routing-patterns` skill as the single source of truth for current Claude IDs, cost tiers, and fallback chains instead of duplicating a tier table that would drift with every Anthropic release.
+
+### Fixed
+- **`GEMINI.md` missed 5 skills from v2.7.0** — `generate:all` was not re-run before the v2.7.0 release tag, so `GEMINI.md` did not list `prompt-caching-patterns`, `json-mode-patterns`, `content-moderation-patterns`, `model-routing-patterns`, or `/mcp-builder`. Regenerated.
+- **`manifest.json` stale skill counts** — `components.skills.description` and `modules.skills.description` still reported `94 skills (31 task + 31 hybrid + 32 knowledge)` instead of the current `99 skills (32 task + 31 hybrid + 36 knowledge)`. Fixed in 2 places.
+
+---
+
 ## v2.7.1 — Eject Output-Styles Fix (2026-04-17)
 
 ### Fixed

package/README.md

@@ -10,10 +10,9 @@
 
 ---
 
-## What's New in v2.7.1
+## What's New in v2.7.3
 
-- **`ai-toolkit eject` now copies `app/output-styles/*.md`** — pre-existing gap since output-styles were introduced: eject produced a standalone `.claude/` without any system-prompt styles, so `golden-rules`, `learning`, and `explanatory` silently dropped out after ejecting. Now eject writes `.claude/output-styles/` with all source `.md` files and reports the count in the summary line: `Ejected: N agents, N skills, N rules, N output style(s)`.
-- **2 new `tests/test_eject.bats` cases** covering output-styles: directory created + file count matches source + `golden-rules.md` baseline, and summary line reports correct count. Test count: 664 → 666.
+- **`llms.txt` + `llms-full.txt` regenerated** after PR #7 (Medplum/FHIR rules) — catalogs now list `medplum-docs-map.md` and the language-rules reference advertises the correct counts: `14 languages / 73 rule files` (was `13 / 68`).
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/ai-engineer.md

@@ -64,6 +64,8 @@ AI/ML integration specialist for production systems, including RAG pipeline desi
 | Complex reasoning | Large | Claude Opus, GPT-4 |
 | Local/private | Open | Llama, Mistral |
 
+For current Claude model IDs, cost tiers, and fallback chains see the `model-routing-patterns` skill — the single source of truth that gets bumped with each Anthropic release.
+
 ### Embedding Selection
 | Use Case | Model |
 |----------|-------|

package/app/rules/medplum/coding-style.md

@@ -0,0 +1,56 @@
+---
+language: medplum
+category: coding-style
+version: "1.0.0"
+---
+
+# Medplum / FHIR Coding Style
+
+## Resource Structure
+- Every FHIR object must include `resourceType` as first field.
+- Use PascalCase for resource types (`Patient`, `ServiceRequest`), camelCase for fields (`birthDate`, `valueQuantity`).
+- Never hardcode resource IDs. Let the server assign them on create.
+- Include `meta.profile` when creating resources that must conform to a StructureDefinition.
+
+## References
+- Use `createReference(resource)` from `@medplum/core` to build Reference objects.
+- Always include `display` on references for human readability.
+- Use `getReferenceString(resource)` for comparisons and logging — returns `ResourceType/id`.
+- Use `parseReference(ref)` to extract resourceType and id from a reference string.
+- Never concatenate strings to build references manually.
+
+## CodeableConcepts & Coding
+- Always include `system`, `code`, and `display` in every Coding element.
+- Use standard terminology URIs: `http://loinc.org`, `http://snomed.info/sct`, `http://hl7.org/fhir/sid/icd-10-cm`.
+- Use `getCodeBySystem(cc, system)` to find codes; `setCodeBySystem(cc, system, code)` to set them.
+- Prefer `CodeableConcept` over plain `Coding` when the FHIR spec allows both — it supports multiple codings and free text.
+
+## Identifiers
+- Use `identifier` arrays with `system` + `value` for external IDs (MRN, NPI, SSN).
+- Use `getIdentifier(resource, system)` and `setIdentifier(resource, system, value)` helpers.
+- Identifier systems must be absolute URIs (e.g., `http://hl7.org/fhir/sid/us-npi`).
+- Use `createResourceIfNoneExist(resource, 'identifier=system|value')` for idempotent creates.
+
+## Extensions
+- Use the `extension` array with `url` and typed `value[x]` fields.
+- Prefer official HL7/US Core extensions over custom ones where they exist.
+- Use `getExtension(resource, url)` and `getExtensionValue(resource, url)` helpers.
+
+## Bundles
+- Use `urn:uuid:<uuid>` for internal references between entries in a transaction Bundle.
+- Every Bundle entry must have `request.method` (`POST`, `PUT`, `DELETE`) and `request.url`.
+- Include `fullUrl` on entries that are referenced by other entries.
+- Use conditional references (`Practitioner?identifier=npi|123`) for existing resources.
+
+## HIPAA-Aware Coding
+- Identifiers like SSN, MRN, and insurance IDs are PHI — never log raw values to console or external services.
+- Use a safe logging utility (e.g., `safeLog()`) for any output that might contain patient data. Never `console.log` raw FHIR resources.
+- Reference `display` strings may contain patient names — treat as PHI in logs and error messages.
+- Every new data access path or admin operation must include corresponding `AuditEvent` creation. No exceptions.
+- When audit logging fails (Medplum unreachable), write to a fallback store — audit events must never be silently dropped.
+- See `security.md` rules for full HIPAA, access policy, and PHI handling requirements.
+
+## Formatting
+- Use `formatHumanName()`, `formatAddress()`, `formatDate()`, `formatQuantity()` for display strings.
+- Use `getDisplayString(resource)` as a universal fallback for any resource's display name.
+- Never manually concatenate name parts — FHIR names have `given[]`, `family`, `prefix[]`, `suffix[]`.

package/app/rules/medplum/frameworks.md

@@ -0,0 +1,51 @@
+---
+language: medplum
+category: frameworks
+version: "1.0.0"
+---
+
+# Medplum Frameworks
+
+## @medplum/core — SDK Client
+- Use `MedplumClient` for all FHIR operations. Never use raw `fetch` against Medplum endpoints.
+- Use `medplum.createResource()`, `readResource()`, `updateResource()`, `deleteResource()` for CRUD.
+- Use `medplum.searchResources()` for typed arrays. Use `medplum.searchOne()` when expecting a single result.
+- Use `medplum.executeBatch()` for transaction Bundles — groups multiple operations atomically.
+- Use `medplum.upsertResource(resource, query)` for atomic create-or-update.
+- Use `medplum.createResourceIfNoneExist(resource, query)` for idempotent creation.
+- Configure `autoBatchTime` on MedplumClient to auto-batch concurrent GET requests. Use `Promise.all()` instead of sequential `await` to benefit from batching.
+
+## @medplum/fhirtypes — Type Safety
+- Import FHIR types directly: `import { Patient, Observation } from '@medplum/fhirtypes'`.
+- Use TypeScript types for all FHIR resources — never use `any` for resource data.
+- Cast `event.input` in bot handlers: `const patient = event.input as Patient`.
+- Use optional chaining for nested FHIR fields: `patient.name?.[0]?.given?.[0]`.
+
+## @medplum/react — UI Components
+- Wrap app with `<MedplumProvider client={medplum}>` at the root.
+- Use `useMedplum()` hook to access the MedplumClient instance in components.
+- Use `useMedplumContext()` for client + profile + loading state together.
+- Use `<ResourceForm>` for auto-generated CRUD forms, `<ResourceTable>` for display.
+- Use `<SearchControl>` for searchable/filterable resource lists.
+- Use `<QuestionnaireForm>` to render FHIR Questionnaires and capture responses.
+- Use `useSubscription(criteria)` for real-time WebSocket data in React components.
+- Requires Mantine 7+ and PostCSS with Mantine preset. Import `@mantine/core/styles.css`.
+
+## Bot Development
+- Export a single `handler` function: `export async function handler(medplum: MedplumClient, event: BotEvent)`.
+- Access trigger resource via `event.input`. Access secrets via `event.secrets`.
+- Use `event.contentType` to determine input format (`application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`).
+- Deploy bots via CLI for CI/CD: `medplum bot deploy <bot-name>`.
+- Apply AccessPolicies to bots — restrict to minimum required resource types.
+- Use Subscriptions with `channel.type: 'rest-hook'` and `channel.endpoint: 'Bot/<ID>'` for event-driven execution.
+
+## GraphQL
+- Append `List` to resource type for searches: `PatientList(name: "Eve")`.
+- Use snake_case for search parameters in GraphQL (not kebab-case): `address_city`, not `address-city`.
+- Use inline fragments for reference resolution: `... on Observation { valueQuantity { value } }`.
+- Use `_reference` for reverse lookups: `EncounterList(_reference: patient)`.
+
+## CLI (@medplum/cli)
+- Use `medplum login` for auth, `medplum get`/`medplum post` for FHIR operations.
+- Use `medplum bot deploy` for bot deployment in CI/CD pipelines.
+- Use `medplum bulk export` for bulk data operations.

package/app/rules/medplum/patterns.md

@@ -0,0 +1,61 @@
+---
+language: medplum
+category: patterns
+version: "1.0.0"
+---
+
+# Medplum / FHIR Patterns
+
+## Bundle Transactions
+- Use `type: 'transaction'` for atomic multi-resource operations — all-or-nothing.
+- Use `type: 'batch'` when operations are independent and partial failure is acceptable.
+- Use `urn:uuid:<uuid>` in `fullUrl` for forward references between entries.
+- Reference other entries via `{ reference: 'urn:uuid:<uuid>' }`.
+- Use `ifNoneExist` on POST entries for conditional creation (idempotent).
+- Use `ifMatch: 'W/"versionId"'` on PUT entries for optimistic concurrency.
+- Use conditional references for existing resources: `Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|123`.
+- For large bundles (>50MB), use `Prefer: respond-async` header.
+
+## Search Patterns
+- Use `_include=ResourceType:searchParam` to fetch referenced resources in one call.
+- Use `_revinclude=ResourceType:searchParam` to fetch resources referencing your results.
+- Use `:iterate` modifier for multi-hop traversal: `_include:iterate=Patient:general-practitioner`.
+- Use `_count` + `_offset` for pagination; use `searchResourcePages()` for async iteration.
+- Use `:contains` modifier for substring search on string params: `name:contains=eve`.
+- Use `:not` modifier to exclude: `status:not=completed`.
+- Use comma-separated values for OR: `status=active,on-hold`.
+- Use multiple parameters for AND: `name=Simpson&birthdate=1940-03-29`.
+- Prefer `searchResources()` over `search()` — returns typed array, not raw Bundle.
+
+## Subscription & Bot Workflows
+- Create a `Subscription` resource with `criteria` (FHIR search query) and `channel.type: 'rest-hook'`.
+- Point `channel.endpoint` to `Bot/<BOT_ID>` for automated processing.
+- Use `subscribeToCriteria()` client-side for WebSocket real-time updates.
+- Never subscribe to `AuditEvent` changes — prevents notification spirals.
+- Use cron-based bots for scheduled tasks (e.g., daily reports, batch processing).
+
+## Access Policies
+- Define `AccessPolicy.resource[]` with `resourceType` and optional `criteria`, `readonly`, `hiddenFields`, `readonlyFields`.
+- Use `%profile` variable to scope data to the current user: `Observation?performer=%profile`.
+- Use `%patient` variable for patient-portal access: `Observation?subject=%patient`.
+- Use compartment-based access for patient-scoped isolation.
+- Use `writeConstraint` with FHIRPath for state machine enforcement (e.g., prevent status rollback).
+- Apply least privilege: start with no access, add specific resource types.
+
+## Conditional Operations
+- Use `createResourceIfNoneExist(resource, query)` for idempotent creates keyed on identifier.
+- Use `upsertResource(resource, query)` for atomic create-or-update in a single request.
+- Use `If-None-Exist` header on POST for server-side conditional creation.
+
+## Patient Deduplication
+- Match on `identifier` systems (MRN, SSN, insurance ID) for deterministic matching.
+- Use probabilistic matching on name + birthdate + address for fuzzy matches.
+- Use Patient `link` field with `type: 'replaced-by'` for merge workflows.
+- Prefer `createResourceIfNoneExist()` at ingestion to prevent duplicates.
+
+## Questionnaire Workflows
+- Create `Questionnaire` resources for form definitions. Use `linkId` for question identification.
+- Use `QuestionnaireResponse` for captured answers. Link to Questionnaire via `questionnaire` field.
+- Use `getQuestionnaireAnswers(response)` to extract answers as a map keyed by `linkId`.
+- Automate post-submission processing with a Bot subscribed to `QuestionnaireResponse` creation.
+- Use SDC (Structured Data Capture) extensions for advanced rendering and extraction.

package/app/rules/medplum/security.md

@@ -0,0 +1,58 @@
+---
+language: medplum
+category: security
+version: "1.0.0"
+---
+
+# Medplum / FHIR Security
+
+## Authentication
+- Use client credentials flow (`startClientLogin`) for backend services and integrations.
+- Use authorization code flow (`startLogin` + `processCode`) for user-facing web apps.
+- Never store tokens in `localStorage` in production — use secure HTTP-only cookies or server-side sessions.
+- Use `refreshIfExpired()` before critical operations. Set `gracePeriod` to refresh proactively.
+- Use `setBasicAuth(clientId, clientSecret)` only for server-side code, never in browser.
+- Rotate client secrets via `$rotate-client-secret` operation periodically.
+
+## Access Policies
+- Every non-admin user must have an AccessPolicy. Never leave users with default full access.
+- Scope to specific resource types: list only the types the user needs.
+- Use `readonly: true` or explicit `interaction` arrays to restrict write access.
+- Use `criteria` with FHIR search syntax to filter visible resources (e.g., `Patient?organization=Organization/123`).
+- Use `hiddenFields` to prevent sensitive fields from being returned (e.g., SSN).
+- Use `readonlyFields` to allow viewing but prevent modification of specific fields.
+- Use `writeConstraint` FHIRPath expressions for business rules (e.g., prevent status rollback on finalized resources).
+- Test access policies by logging in as a test user with the policy applied.
+
+## HIPAA & Audit Logging
+- Medplum automatically creates AuditEvent resources for all FHIR operations.
+- Never log PHI (patient names, identifiers, health data) to application console or external services.
+- Use structured audit references: reference the Patient and the accessing Practitioner in audit records.
+- For custom audit trails, create AuditEvent resources with `type`, `agent`, `entity`, and `outcome`.
+- Ensure audit events are never silently dropped — if Medplum is unreachable, write to a fallback store.
+
+## PHI Handling
+- Never include PHI in URLs, query parameters, or HTTP headers.
+- Use POST-based search for queries containing sensitive criteria.
+- Use `Binary` resources with `securityContext` for sensitive file attachments.
+- Encrypt data at rest and in transit (TLS 1.2+). Medplum hosted handles this automatically.
+- Apply data retention policies — use `$expunge` operation for permanent deletion when required.
+
+## SMART Scopes
+- Use `patient/*.read` style scopes for patient-facing apps.
+- Use `user/*.read` style scopes for practitioner-facing apps.
+- Validate scopes server-side on every request — do not trust client-side scope claims.
+- Use `launch/patient` context for apps launched within a patient context.
+- Define minimal scopes: request only the resource types and operations needed.
+
+## Multi-Tenant Isolation
+- Use Medplum Projects for tenant isolation — each project is a separate data silo.
+- Never share AccessPolicies across projects/tenants.
+- Validate `meta.project` on operations when building multi-tenant middleware.
+- Use separate ClientApplications per tenant for backend integrations.
+
+## Secrets Management
+- Use Bot secrets (`event.secrets`) for API keys, connection strings, and credentials.
+- Never hardcode secrets in bot source code or resource data.
+- Use Medplum project-level secrets storage — accessible only by project admins.
+- Rotate secrets on a regular schedule and after any suspected compromise.

package/app/rules/medplum/testing.md

@@ -0,0 +1,56 @@
+---
+language: medplum
+category: testing
+version: "1.0.0"
+---
+
+# Medplum / FHIR Testing
+
+## MockClient
+- Use `MockClient` from `@medplum/mock` for unit tests — it simulates the full MedplumClient API in memory.
+- Pre-populate test data with `mockClient.createResource()` before running test assertions.
+- MockClient supports `search`, `searchResources`, `searchOne`, `readResource`, `updateResource`, `deleteResource`.
+- MockClient does not require network access — tests run fast and offline.
+- Use `new MockClient()` per test to ensure isolation between test cases.
+
+## Bot Unit Testing
+- Test the handler function directly: `await handler(mockClient, mockEvent)`.
+- Create mock `BotEvent` objects with `input`, `contentType`, `secrets`, and `bot` fields.
+- Verify resource creation: call `mockClient.searchResources()` after handler execution.
+- Test error paths: pass invalid input resources and assert the handler throws or returns errors.
+- Test different content types: `application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`.
+- Mock `event.secrets` for bots that depend on external API keys.
+
+## Resource Validation
+- Use `validateResource(resource)` from `@medplum/core` to check resources against StructureDefinitions.
+- Test that required fields produce `OperationOutcome` errors when missing.
+- Test custom profiles: create a `StructureDefinition` resource, then validate resources against it.
+- Use the `$validate` operation for server-side validation in integration tests.
+- Test the Data Absent Reason extension when required fields may legitimately be empty.
+
+## Search Testing
+- Test search parameter behavior: exact match vs prefix match vs substring (`name`, `name:exact`, `name:contains`).
+- Verify `_include` returns related resources in the Bundle.
+- Test pagination with `_count` and `_offset` parameters.
+- Test token search with and without system namespace: `identifier=value` vs `identifier=system|value`.
+- Test date range searches with comparison prefixes: `ge`, `le`, `gt`, `lt`.
+
+## Integration Testing
+- Use Medplum Docker image (`medplum/medplum-server`) for local integration tests.
+- Test full workflows end-to-end: create patient → create observation → search → verify.
+- Verify Bundle transactions are atomic: intentionally fail one entry and confirm rollback.
+- Test access policies by authenticating as users with different policies.
+- Test Subscription triggers: create a Subscription, modify a matching resource, verify Bot execution.
+
+## Test Data Factories
+- Create typed factory functions: `createTestPatient(overrides?)`, `createTestObservation(overrides?)`.
+- Use realistic but synthetic data — never use real patient data in tests.
+- Include only minimal required fields by default. Let tests add specific fields via overrides.
+- Use `generateId()` from `@medplum/core` for unique test identifiers.
+- Use standard test identifier systems: `http://example.com/test-mrn` to avoid collision with real systems.
+
+## Assertions
+- Assert on `OperationOutcome` for error responses: check `issue[].severity`, `issue[].code`, `issue[].expression`.
+- Use `isOk(outcome)` and `isNotFound(outcome)` from `@medplum/core` for status checks.
+- Use `deepEquals(a, b)` for resource comparison (ignores `meta.versionId` and `meta.lastUpdated`).
+- Assert reference integrity: verify `subject.reference` matches expected `Patient/id` format.

package/kb/reference/language-rules.md

@@ -6,14 +6,14 @@ tags: [rules, languages, coding-style, testing, patterns, security]
 version: "1.0.0"
 created: "2026-04-07"
 last_updated: "2026-04-07"
-description: "Reference for the language-specific rules system: 13 languages, 5 categories per language, auto-detection."
+description: "Reference for the language-specific rules system: 14 languages, 5 categories per language, auto-detection."
 ---
 
 # Language Rules System
 
 ## Overview
 
-ai-toolkit ships language-specific rule files covering 13 programming languages plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships language-specific rule files covering 14 languages/platforms plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
 
 Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
 
@@ -48,10 +48,11 @@ app/rules/
 ├── csharp/
 ├── php/
 ├── cpp/
-└── ruby/
+├── ruby/
+└── medplum/
 ```
 
-**Total: 13 directories × 5 files each + 3 standalone = 68 rule files** (see README.md for canonical count)
+**Total: 14 directories × 5 files each + 3 standalone = 73 rule files** (see README.md for canonical count)
 
 ## Supported Languages
 
@@ -70,6 +71,7 @@ app/rules/
 | PHP | `rules/php/` | `composer.json` |
 | C++ | `rules/cpp/` | `CMakeLists.txt`, `Makefile`, `*.cpp` |
 | Ruby | `rules/ruby/` | `Gemfile`, `*.gemspec` |
+| Medplum | `rules/medplum/` | `medplum.config.mts`, `medplum.config.ts` |
 
 ## Rule Categories
 
@@ -107,6 +109,7 @@ Scans for configuration files defined in each module's `auto_detect` list in `ma
 10. `Package.swift` → Swift
 11. `*.csproj` or `*.sln` → C#
 12. `CMakeLists.txt` or `Makefile` → C++
+13. `medplum.config.mts` or `medplum.config.ts` → Medplum
 
 ### Phase 2: Source file extensions (actual code presence)
 
@@ -163,6 +166,7 @@ Language rules are tracked as modules in `manifest.json`:
 | `rules-php` | PHP-specific rules |
 | `rules-cpp` | C++-specific rules |
 | `rules-ruby` | Ruby-specific rules |
+| `rules-medplum` | Medplum/FHIR healthcare platform rules |
 
 ## Rules vs Skills