Skip to content

Commit 7cf0f33

Browse files
committed
improvement(audits): add check:guidance-refs and fix the stale references it found
Agent guidance (CLAUDE.md, every AGENTS.md, .claude/rules, .agents/skills) names paths, scripts, skills, and import specifiers that agents follow literally. The new audit resolves each one and fails on any that no longer exists. Fixes the references it found: lib/copilot -> lib/mothership, stores/workflows/store -> stores/workflows/workflow/store, a relative landing path, deleted selector-provider and legacy landing mentions, and illustrative example imports rewritten as placeholders.
1 parent 771a736 commit 7cf0f33

22 files changed

Lines changed: 353 additions & 32 deletions

File tree

‎.agents/skills/add-block/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -697,7 +697,7 @@ export const ServiceV2Block: BlockConfig = {
697697
Register the block in `apps/sim/blocks/registry-maps.ts` — add the import and an entry to each map alphabetically:
698698

699699
```typescript
700-
import { ServiceBlock, ServiceBlockMeta } from '@/blocks/blocks/service'
700+
import { ServiceBlock, ServiceBlockMeta } from '@/blocks/blocks/{service}'
701701

702702
export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
703703
// ... existing blocks ...

‎.agents/skills/add-enrichment/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ Rules:
118118
In `apps/sim/enrichments/registry.ts`, import and add the entry (catalog order is registration order):
119119

120120
```typescript
121-
import { myEnrichment } from '@/enrichments/my-enrichment'
121+
import { myEnrichment } from '@/enrichments/{id}/{id}'
122122

123123
export const ENRICHMENT_REGISTRY: EnrichmentRegistry = {
124124
// ...existing

‎.agents/skills/add-integration/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,8 @@ Three rules that are easy to get wrong when copying from existing blocks:
128128
- Every remote `selectorKey` must use the unified server selector path. Apply the `add-selector` skill:
129129
add browser-safe metadata to `apps/sim/lib/selectors/manifest.ts`, reuse or extract a server-only
130130
provider listing primitive, and add a credential- and destination-bound server attachment. Do not
131-
add code under `hooks/selectors/providers`, a provider-specific query key, browser token acquisition,
132-
or a selector-only API route. The shared context builder sends only active `dependsOn` values and
131+
add a client provider fetcher, a provider-specific query key, browser token acquisition, or a
132+
selector-only API route. The shared context builder sends only active `dependsOn` values and
133133
preserves exact `{{KEY}}` environment references for server-side resolution.
134134
- A `canonicalParamId` is a third name that neither member of a basic/advanced pair uses as its `id`
135135
(e.g. `channelSelector` + `channelId` → `canonicalParamId: 'channel'`). It is the only key that

‎.agents/skills/add-permission-group-item/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,7 @@ Add a case to `capabilities.test.ts` for any rule with logic beyond reading one
197197
| Guarded root | Forbidden |
198198
|---|---|
199199
| `lib/core/application/index.ts`, and `lib/permission-groups/` `capabilities.ts` / `capability-assertions.ts` / `config-scope.server.ts` | `providers/`, `blocks/`, `tools/`, `executor/`, `lib/uploads/`, `lib/workflows/` |
200-
| `lib/core/utils/with-route-handler.ts` | those six **plus** `lib/billing/`, `lib/permission-groups/resolve.server`, `lib/auth`, `lib/copilot/`, `lib/knowledge/` |
200+
| `lib/core/utils/with-route-handler.ts` | those six **plus** `lib/billing/`, `lib/permission-groups/resolve.server`, `lib/auth`, `lib/mothership/`, `lib/knowledge/` |
201201

202202
`lib/billing/` stays allowed for the funnel roots because `resolve.server.ts` legitimately reads the subscription to decide whether an organization is on an enterprise plan; the wrapper is a lifecycle shim that opens the memo scope and nothing more. That split is why the scope is two files.
203203

‎.agents/skills/add-selector/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Keep connector selector/manual canonical pairs and fork reconfiguration behavior
9898

9999
Do not add:
100100

101-
- A module under `hooks/selectors/providers` or any client provider fetcher.
101+
- A client provider fetcher.
102102
- A provider-specific React Query key.
103103
- A selector-specific OAuth-token request.
104104
- A selector-only API route when the provider primitive can be called directly.

‎.agents/skills/migrate-application-operation/SKILL.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,16 +47,16 @@ Read these files completely before editing:
4747
- `apps/sim/lib/api/server/routes/internal-json-route.ts`
4848
- `apps/sim/lib/api/server/routes/v2-json-route.ts`
4949
- `apps/sim/lib/auth/internal-delegation.ts`
50-
- `apps/sim/lib/copilot/application/application-adapter.ts`
51-
- `apps/sim/lib/copilot/auth/application-delegation.ts`
50+
- `apps/sim/lib/mothership/application/application-adapter.ts`
51+
- `apps/sim/lib/mothership/auth/application-delegation.ts`
5252

5353
Use the file domain only as a representative golden slice:
5454

5555
- `apps/sim/lib/workspace-files/application/operations.ts`
5656
- `apps/sim/lib/workspace-files/application/authorized-workspace-file-use-case.ts`
5757
- `apps/sim/lib/workspace-files/application/rename-workspace-file.ts`
58-
- `apps/sim/lib/copilot/application/execute-file-use-case.ts`
59-
- `apps/sim/lib/copilot/auth/file-delegation.ts`
58+
- `apps/sim/lib/mothership/application/execute-file-use-case.ts`
59+
- `apps/sim/lib/mothership/auth/file-delegation.ts`
6060

6161
Then read the target domain's operation registry, application code, repositories, contracts, adapters, aliases, resume paths, and focused tests. Fail immediately if the shared foundation is absent. Do not recreate it inside the domain.
6262

@@ -250,7 +250,7 @@ Keep v1 middleware and routes unchanged unless explicitly included.
250250

251251
## Adapt Copilot
252252

253-
Copilot is a surface adapter, not a separate application layer. If an HTTP or other surface already uses an application use case, Copilot must call that exact use case rather than reimplementing protected business behavior under `lib/copilot`.
253+
Copilot is a surface adapter, not a separate application layer. If an HTTP or other surface already uses an application use case, Copilot must call that exact use case rather than reimplementing protected business behavior under `lib/mothership`.
254254

255255
Create one domain-level Copilot application adapter with `createCopilotApplicationAdapter` instead of constructing delegated principals in every tool:
256256

‎.agents/skills/ship/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ When the user runs `/ship`:
4848
- `bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy.
4949
6. **Run pre-ship checks** from the repo root before staging. This has two phases: first **regenerate** every committed artifact so generated files never drift into a CI failure (this is what catches things like `agent-stream-docs` going stale after a `models.ts` edit), then run the **full audit suite** CI's `Lint and Test` job enforces. Both phases parallelize — but only across commands that write **disjoint** outputs — and a bare `wait` swallows child exit codes, so both phases below explicitly collect each job's status and abort ship if any failed.
5050

51-
**Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/copilot/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync):
51+
**Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync):
5252
```bash
5353
rm -f /tmp/ship-gen-results
5454
for g in agent-stream-docs:generate docs-manifest:generate skills:sync; do
@@ -63,7 +63,7 @@ When the user runs `/ship`:
6363
```
6464
Then `git status --short` to see what regenerated — those files must be staged in step 7 alongside your own changes.
6565

66-
**Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/copilot/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `integration-catalog:check` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present.
66+
**Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/mothership/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `integration-catalog:check` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present.
6767

6868
**Phase B — run lint + every audit CI enforces, in parallel, and abort ship if any fails.** Before running the commands, compare this list with `.github/workflows/test-build.yml`; when CI adds an audit, run it and update this skill instead of trusting a stale snapshot. The env-flag audit is currently an inline workflow block rather than a package script: when `apps/sim/lib/core/config/env-flags.ts` changed, run that current workflow block verbatim instead of copying a second version into this skill. Run `bun run lint` first (it autofixes formatting and mutates files, so don't parallelize it with the read-only audits), then run the base-sensitive block-registry check, then fan the independent audits out and collect exit codes:
6969
```bash

‎.claude/rules/landing-seo-geo.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ paths:
1616
- All internal navigation uses Next.js `<Link>` with real `href`s — never `onClick` navigation. External links get `rel="noopener noreferrer"`.
1717
- All copy is server-rendered text: no text baked into images, no content that exists only after a client effect runs.
1818
- Navbar is a Server Component (no `'use client'`) for immediate crawlability. Logo `<Image>` has `priority` (LCP element). The navbar `<nav>` carries `SiteNavigationElement` schema.org markup.
19-
- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`components/home-structured-data/`).
19+
- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`apps/sim/app/(landing)/components/home-structured-data/`).
2020
- After adding routes or anchors, verify `app/sitemap.ts` and `app/robots.ts` still reflect reality.
2121

2222
## GEO (Generative Engine Optimisation)

‎.claude/rules/sim-imports.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ paths:
1414
```typescript
1515
// ✓ Good
1616
import { Chip } from '@sim/emcn'
17-
import { useWorkflowStore } from '@/stores/workflows/store'
17+
import { useWorkflowStore } from '@/stores/workflows/workflow/store'
1818

1919
// ✗ Bad
20-
import { useWorkflowStore } from '../../../stores/workflows/store'
20+
import { useWorkflowStore } from '../../../stores/workflows/workflow/store'
2121
```
2222

2323
## Barrel Exports

‎.claude/rules/sim-queries.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ The `'use client'` hook module then imports these back for its hooks. **Never**
5757

5858
```typescript
5959
import { requestJson } from '@/lib/api/client/request'
60-
import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
60+
import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/<domain>'
6161

6262
export const ENTITY_LIST_STALE_TIME = 60 * 1000
6363

0 commit comments

Comments
 (0)