@tsfpp/agents 1.0.0

package/copilot/instructions/tsfpp-prelude.instructions.md

@@ -0,0 +1,141 @@
+---
+applyTo: "**/*.ts"
+---
+
+# TSF++ prelude API
+
+Full reference: `node_modules/@tsfpp/prelude/README.md`
+Recipes: `node_modules/@tsfpp/prelude/RECIPES.md`
+
+## Import
+
+```ts
+import {
+  // ADT constructors
+  some, none, ok, err,
+  // Type guards
+  isSome, isNone, isOk, isErr,
+  // Option combinators
+  mapO, flatMapO, orElse, getOrElse, fromNullable,
+  // Result combinators
+  map, flatMap, flatMapAsync, mapErr, tap, tapErr,
+  // Async adapters
+  tryCatch, tryCatchAsync,
+  // Traversal
+  traverseArray, traverseArrayO, sequenceArrayO,
+  // Pipe
+  pipe, flow, comp, complement,
+  // Utilities
+  absurd, unit,
+  // Types
+  type Option, type Result, type Unit, type Brand,
+} from '@tsfpp/prelude'
+```
+
+Never `import from 'ramda'`.
+
+## Option\<A\>
+
+```ts
+// Construct
+const a: Option<number> = some(42)
+const b: Option<number> = none
+
+// Guard before accessing .value
+if (isSome(opt)) opt.value   // safe
+if (isNone(opt)) return ...  // early exit
+
+// Transform
+pipe(opt, mapO(n => n + 1))
+pipe(opt, flatMapO(n => n > 0 ? some(n) : none))
+pipe(opt, getOrElse(() => 0))
+pipe(opt, orElse(() => some(defaultValue)))
+
+// Lift from nullable
+const opt = fromNullable(maybeNull)  // null | undefined → Option<T>
+```
+
+## Result\<T, E\>
+
+```ts
+// Construct
+const r: Result<number, string> = ok(42)
+const e: Result<number, string> = err('oops')
+
+// Guard before accessing .value / .error
+if (isOk(r))  r.value   // T
+if (isErr(r)) r.error   // E
+
+// Transform
+pipe(r, map(v => v + 1))
+pipe(r, flatMap(v => v > 0 ? ok(v) : err('non-positive')))
+pipe(r, mapErr(e => `Wrapped: ${e}`))
+
+// Side effects without breaking the chain
+pipe(r, tap(v  => log.debug({ v })))
+pipe(r, tapErr(e => log.warn({ e })))
+
+// Async adapter — wraps throwing code
+const result = await tryCatchAsync(
+  () => db.findById(id),
+  e  => mkDbError(e),
+)
+
+// Sync adapter
+const result = tryCatch(
+  () => JSON.parse(raw),
+  e  => `parse error: ${e}`,
+)
+```
+
+## pipe
+
+```ts
+const result = pipe(
+  input,
+  mapO(transform),
+  flatMapO(validate),
+  getOrElse(() => fallback),
+)
+```
+
+## Unit
+
+```ts
+// Success with no meaningful value — use ok(unit), not ok(undefined)
+const save = (): Result<Unit, DbError> => ok(unit)
+```
+
+## absurd
+
+```ts
+// Exhaustiveness witness — type error if a union variant is unhandled
+default: return absurd(x)
+```
+
+## Brand
+
+```ts
+type TrackId = Brand<string, 'TrackId'>
+
+const mkTrackId = brand<string, 'TrackId'>(
+  s => s.length > 0,
+  s => `Invalid TrackId: "${s}"`,
+)
+```
+
+## Traversal
+
+```ts
+// ReadonlyArray<A> → (A → Result<B, E>) → Result<ReadonlyArray<B>, E>
+const results = traverseArray(validate)(items)
+
+// ReadonlyArray<A> → (A → Option<B>) → Option<ReadonlyArray<B>>
+const options = traverseArrayO(lookup)(items)
+```
+
+## Discriminant convention
+
+- Prelude ADTs use `_tag` internally — **never access it directly**
+- Use exported guards: `isSome`, `isNone`, `isOk`, `isErr`
+- Domain ADTs use `kind` as discriminant

package/copilot/instructions/tsfpp-react.instructions.md

@@ -0,0 +1,87 @@
+---
+applyTo: "**/*.tsx"
+---
+
+# TSF++ React rules
+
+Full standard: `node_modules/@tsfpp/standard/REACT_CODING_STANDARD.md`
+Extends: tsfpp-base.instructions.md (all base rules apply to `.tsx` too)
+
+## Component shape
+
+```ts
+// Props: readonly record, no optional fields — use Option<T>
+type TrackCardProps = {
+  readonly track: Track
+  readonly onSelect: Option<(id: TrackId) => void>
+}
+
+// Component: pure function, explicit return type
+const TrackCard = ({ track, onSelect }: TrackCardProps): React.ReactElement => { ... }
+```
+
+## State
+
+Model state as a discriminated union — never boolean soup:
+
+```ts
+// Yes
+type LoadState =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'loading' }
+  | { readonly kind: 'success'; readonly data: ReadonlyArray<Track> }
+  | { readonly kind: 'error';   readonly message: string }
+
+// No
+const [isLoading, setIsLoading] = useState(false)
+const [hasError, setHasError] = useState(false)
+const [data, setData] = useState(null)
+```
+
+## Data fetching
+
+Use TanStack Query. Never `useEffect` for fetching:
+
+```ts
+// Yes
+const { data, isPending, isError } = useQuery({ queryKey: ['tracks'], queryFn: fetchTracks })
+
+// No
+useEffect(() => { fetch('/api/tracks').then(...) }, [])
+```
+
+## useEffect
+
+Allowed only for genuine external synchronisation (DOM events, third-party library lifecycle, WebSocket). Must include a comment explaining why `useEffect` is the only option:
+
+```ts
+useEffect(() => {
+  // NOTE(author, date): Syncing to external ResizeObserver — no React equivalent
+  const observer = new ResizeObserver(...)
+  return () => observer.disconnect()
+}, [ref])
+```
+
+## Forbidden in React
+
+- `useEffect` for data fetching or derived state
+- Prop drilling > 2 levels — lift state or use context/Jotai
+- `any` in prop types or event handlers
+- Mutable refs as state (`useRef` for values that drive rendering)
+- Inline object/array literals in JSX props without `useMemo`
+
+## Event handlers
+
+```ts
+// Yes — named, explicit type
+const handleSelect = (id: TrackId): void => { ... }
+
+// No — inline arrow in JSX prop recreated every render
+<Button onClick={() => doSomething(id)} />
+```
+
+## Memoisation
+
+- Wrap expensive computations in `useMemo`
+- Wrap callbacks passed to child components in `useCallback`
+- Do not memoize everything — only when a profiler or render trace shows it matters

package/copilot/prompts/tsfpp-boundary-review.prompt.md

@@ -0,0 +1,152 @@
+---
+description: Scaffolds a new TSF++-compliant module with types, smart constructors, exports, JSDoc, and a test file skeleton.
+name: TSF++ new module
+argument-hint: "module=<name> layer=<core|api|dal|react> description=<one sentence>"
+agent: agent
+tools:
+  - edit/createFile
+  - edit/editFiles
+  - read/readFile
+  - search/fileSearch
+  - vscode/askQuestions
+---
+
+# TSF++ new module
+
+Scaffold a new TSF++-compliant module from scratch.
+
+The canonical standard is at `node_modules/@tsfpp/standard/CODING_STANDARD.md`.
+The prelude API is at `node_modules/@tsfpp/prelude/README.md`.
+
+---
+
+## Required inputs
+
+If any of the following are missing, ask for them before proceeding:
+
+- **Module name** — e.g. `track`, `artist`, `audio-asset`
+- **Layer** — `core` · `api` · `dal` · `react`
+- **Domain description** — one sentence: what does this module represent or do?
+
+---
+
+## What to generate
+
+### 1. Source file — `src/<layer>/<module-name>.ts`
+
+```ts
+/**
+ * @module <module-name>
+ *
+ * <Domain description>.
+ *
+ * @packageDocumentation
+ */
+
+import { type Option, type Result, some, none, ok, err } from '@tsfpp/prelude'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * <What this branded type represents in the domain.>
+ */
+export type <ModuleName>Id = Brand<string, '<ModuleName>Id'>
+
+/**
+ * <What this sum type represents. List variants.>
+ */
+export type <ModuleName> = {
+  readonly id:        <ModuleName>Id
+  readonly <field>:   <Type>
+  // … additional fields
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+/**
+ * Errors that can occur when working with <ModuleName> values.
+ */
+export type <ModuleName>Error =
+  | { readonly kind: 'invalid_id';    readonly raw: string }
+  | { readonly kind: 'not_found';     readonly id:  <ModuleName>Id }
+
+// ─── Smart constructors ───────────────────────────────────────────────────────
+
+/**
+ * Constructs a validated {@link <ModuleName>Id} from a raw string.
+ *
+ * @param raw - The raw string to validate.
+ * @returns `some` with a branded id when valid; `none` when the format is invalid.
+ *
+ * @example
+ * const id = mk<ModuleName>Id('abc-123')
+ * // => some(<ModuleName>Id)
+ */
+export const mk<ModuleName>Id = (raw: string): Option<<ModuleName>Id> =>
+  raw.length > 0 ? some(raw as <ModuleName>Id) : none
+
+/**
+ * Constructs a {@link <ModuleName>} from validated inputs.
+ *
+ * @param params - Validated field values.
+ * @returns `ok` with the constructed value; `err` with a typed error on validation failure.
+ */
+export const mk<ModuleName> = (params: {
+  readonly id:      <ModuleName>Id
+  readonly <field>: <Type>
+}): Result<<ModuleName>, <ModuleName>Error> => {
+  // validate invariants here
+  return ok(params)
+}
+```
+
+### 2. Test file — `src/<layer>/<module-name>.test.ts`
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { isSome, isNone, isOk, isErr } from '@tsfpp/prelude'
+import { mk<ModuleName>Id, mk<ModuleName> } from './<module-name>'
+
+describe('mk<ModuleName>Id', () => {
+  it('returns some for a valid id', () => {
+    expect(isSome(mk<ModuleName>Id('abc-123'))).toBe(true)
+  })
+
+  it('returns none for an empty string', () => {
+    expect(isNone(mk<ModuleName>Id(''))).toBe(true)
+  })
+})
+
+describe('mk<ModuleName>', () => {
+  it('returns ok for valid inputs', () => {
+    // arrange
+    // act
+    // assert
+  })
+
+  it('returns err for invalid inputs', () => {
+    // arrange
+    // act
+    // assert
+  })
+})
+```
+
+---
+
+## Rules
+
+- Never use placeholder comments like `// TODO: implement` in the source file — either implement it or use a properly formatted `// TODO(unknown, <date>): <reason>` marker.
+- The error union must cover every failure mode the smart constructors can produce.
+- Every exported symbol must have a JSDoc block before the file is considered complete.
+- Test file must have at least one passing case and one failing case per smart constructor.
+- Follow layer-specific constraints from `tsfpp-guarded-coding` for the specified layer.
+
+---
+
+## Completion
+
+Report:
+1. Files created and their paths
+2. Exported symbols and their types
+3. Any invariants that still need implementing (listed as `TODO` markers in the source)

package/copilot/prompts/tsfpp-new-module.prompt.md

@@ -0,0 +1,152 @@
+---
+description: Scaffolds a new TSF++-compliant module with types, smart constructors, exports, JSDoc, and a test file skeleton.
+name: TSF++ new module
+argument-hint: "module=<name> layer=<core|api|dal|react> description=<one sentence>"
+agent: agent
+tools:
+  - edit/createFile
+  - edit/editFiles
+  - read/readFile
+  - search/fileSearch
+  - vscode/askQuestions
+---
+
+# TSF++ new module
+
+Scaffold a new TSF++-compliant module from scratch.
+
+The canonical standard is at `node_modules/@tsfpp/standard/CODING_STANDARD.md`.
+The prelude API is at `node_modules/@tsfpp/prelude/README.md`.
+
+---
+
+## Required inputs
+
+If any of the following are missing, ask for them before proceeding:
+
+- **Module name** — e.g. `track`, `artist`, `audio-asset`
+- **Layer** — `core` · `api` · `dal` · `react`
+- **Domain description** — one sentence: what does this module represent or do?
+
+---
+
+## What to generate
+
+### 1. Source file — `src/<layer>/<module-name>.ts`
+
+```ts
+/**
+ * @module <module-name>
+ *
+ * <Domain description>.
+ *
+ * @packageDocumentation
+ */
+
+import { type Option, type Result, some, none, ok, err } from '@tsfpp/prelude'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * <What this branded type represents in the domain.>
+ */
+export type <ModuleName>Id = Brand<string, '<ModuleName>Id'>
+
+/**
+ * <What this sum type represents. List variants.>
+ */
+export type <ModuleName> = {
+  readonly id:        <ModuleName>Id
+  readonly <field>:   <Type>
+  // … additional fields
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+/**
+ * Errors that can occur when working with <ModuleName> values.
+ */
+export type <ModuleName>Error =
+  | { readonly kind: 'invalid_id';    readonly raw: string }
+  | { readonly kind: 'not_found';     readonly id:  <ModuleName>Id }
+
+// ─── Smart constructors ───────────────────────────────────────────────────────
+
+/**
+ * Constructs a validated {@link <ModuleName>Id} from a raw string.
+ *
+ * @param raw - The raw string to validate.
+ * @returns `some` with a branded id when valid; `none` when the format is invalid.
+ *
+ * @example
+ * const id = mk<ModuleName>Id('abc-123')
+ * // => some(<ModuleName>Id)
+ */
+export const mk<ModuleName>Id = (raw: string): Option<<ModuleName>Id> =>
+  raw.length > 0 ? some(raw as <ModuleName>Id) : none
+
+/**
+ * Constructs a {@link <ModuleName>} from validated inputs.
+ *
+ * @param params - Validated field values.
+ * @returns `ok` with the constructed value; `err` with a typed error on validation failure.
+ */
+export const mk<ModuleName> = (params: {
+  readonly id:      <ModuleName>Id
+  readonly <field>: <Type>
+}): Result<<ModuleName>, <ModuleName>Error> => {
+  // validate invariants here
+  return ok(params)
+}
+```
+
+### 2. Test file — `src/<layer>/<module-name>.test.ts`
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { isSome, isNone, isOk, isErr } from '@tsfpp/prelude'
+import { mk<ModuleName>Id, mk<ModuleName> } from './<module-name>'
+
+describe('mk<ModuleName>Id', () => {
+  it('returns some for a valid id', () => {
+    expect(isSome(mk<ModuleName>Id('abc-123'))).toBe(true)
+  })
+
+  it('returns none for an empty string', () => {
+    expect(isNone(mk<ModuleName>Id(''))).toBe(true)
+  })
+})
+
+describe('mk<ModuleName>', () => {
+  it('returns ok for valid inputs', () => {
+    // arrange
+    // act
+    // assert
+  })
+
+  it('returns err for invalid inputs', () => {
+    // arrange
+    // act
+    // assert
+  })
+})
+```
+
+---
+
+## Rules
+
+- Never use placeholder comments like `// TODO: implement` in the source file — either implement it or use a properly formatted `// TODO(unknown, <date>): <reason>` marker.
+- The error union must cover every failure mode the smart constructors can produce.
+- Every exported symbol must have a JSDoc block before the file is considered complete.
+- Test file must have at least one passing case and one failing case per smart constructor.
+- Follow layer-specific constraints from `tsfpp-guarded-coding` for the specified layer.
+
+---
+
+## Completion
+
+Report:
+1. Files created and their paths
+2. Exported symbols and their types
+3. Any invariants that still need implementing (listed as `TODO` markers in the source)

package/init.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * @tsfpp/agents init
+ *
+ * Copies Copilot instructions, chatmodes, prompts, and CLAUDE.md
+ * into the correct locations in the consumer's project.
+ *
+ * Usage:
+ *   pnpm dlx @tsfpp/agents           (one-shot, no install)
+ *   node node_modules/@tsfpp/agents/init.mjs
+ */
+
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync }                            from 'node:fs';
+import { join, dirname }                          from 'node:path';
+import { fileURLToPath }                          from 'node:url';
+import { createInterface }                        from 'node:readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cwd       = process.cwd();
+
+const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+const green  = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+
+// ─── File map ─────────────────────────────────────────────────────────────────
+// Each entry: [source (relative to this file), destination (relative to cwd)]
+
+const FILES = [
+  // Always-on workspace instructions
+  ['copilot/copilot-instructions.md',                    '.github/copilot-instructions.md'],
+
+  // Scoped instruction files
+  ['copilot/instructions/tsfpp-base.instructions.md',    '.github/instructions/tsfpp-base.instructions.md'],
+  ['copilot/instructions/tsfpp-react.instructions.md',   '.github/instructions/tsfpp-react.instructions.md'],
+  ['copilot/instructions/tsfpp-api.instructions.md',     '.github/instructions/tsfpp-api.instructions.md'],
+  ['copilot/instructions/tsfpp-prelude.instructions.md', '.github/instructions/tsfpp-prelude.instructions.md'],
+
+  // Agents
+  ['copilot/agents/tsfpp-guarded-coding.agent.md',       '.github/agents/tsfpp-guarded-coding.agent.md'],
+  ['copilot/agents/tsfpp-audit.agent.md',                '.github/agents/tsfpp-audit.agent.md'],
+  ['copilot/agents/tsfpp-refactor-engineer.agent.md',    '.github/agents/tsfpp-refactor-engineer.agent.md'],
+  ['copilot/agents/tsfpp-annotate.agent.md',             '.github/agents/tsfpp-annotate.agent.md'],
+
+  // Reusable prompts
+  ['copilot/prompts/tsfpp-new-module.prompt.md',         '.github/prompts/tsfpp-new-module.prompt.md'],
+  ['copilot/prompts/tsfpp-boundary-review.prompt.md',    '.github/prompts/tsfpp-boundary-review.prompt.md'],
+
+  // Claude Code
+  ['claude/CLAUDE.md',                                   'CLAUDE.md'],
+];
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function ensureDir(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+console.log();
+console.log(bold('  @tsfpp/agents — init'));
+console.log(dim('  Copies Copilot and Claude Code configuration into your project.\n'));
+
+const results = { copied: [], skipped: [], failed: [] };
+
+for (const [src, dest] of FILES) {
+  const srcPath  = join(__dirname, src);
+  const destPath = join(cwd, dest);
+
+  if (existsSync(destPath)) {
+    const overwrite = await confirm(
+      `  ${yellow('!')} ${dest} already exists. Overwrite? ${dim('[y/N]')} `
+    );
+    if (!overwrite) {
+      results.skipped.push(dest);
+      console.log(`  ${dim('–')} ${dim(dest)} ${dim('(skipped)')}`);
+      continue;
+    }
+  }
+
+  try {
+    await ensureDir(destPath);
+    await copyFile(srcPath, destPath);
+    results.copied.push(dest);
+    console.log(`  ${green('✓')} ${dest}`);
+  } catch (err) {
+    results.failed.push(dest);
+    console.log(`  \x1b[31m✗\x1b[0m ${dest} ${dim(`(${err.message})`)}`);
+  }
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+console.log();
+console.log(dim('  ─────────────────────────────────────────'));
+console.log(`  ${green(results.copied.length + ' copied')}  ${yellow(results.skipped.length + ' skipped')}  ${results.failed.length > 0 ? `\x1b[31m${results.failed.length} failed\x1b[0m` : dim('0 failed')}`);
+console.log();
+
+if (results.failed.length === 0) {
+  console.log('  ' + bold('Done.') + ' Reload VS Code to activate Copilot instructions.');
+  console.log(dim('  Commit the generated files — they are workspace configuration.\n'));
+} else {
+  console.log('  Some files could not be copied. Check the errors above.\n');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tsfpp/agents",
+  "version": "1.0.0",
+  "description": "Workspace AI tooling for TSF++ projects: scoped instructions, coding agents, and reusable prompts",
+  "keywords": [
+    "tsfpp",
+    "copilot",
+    "agents",
+    "instructions",
+    "claude",
+    "functional",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/tsfpp/agents#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsfpp/agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tsfpp/agents/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "tsfpp-agents": "./init.mjs"
+  },
+  "files": [
+    "copilot/",
+    "claude/",
+    "init.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@tsfpp/standard":     ">=1.0.0",
+    "@tsfpp/prelude":      ">=1.0.0",
+    "@tsfpp/boundary":     ">=1.0.0",
+    "@tsfpp/eslint-config":">=1.0.0",
+    "@tsfpp/tsconfig":     ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}