@tsfpp/agents 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -10,6 +10,29 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-05-18
+
+### Added
+
+- Added `copilot/prompts/trunk-changelog.prompt.md` to support trunk-based changelog authoring.
+- Added `copilot/skills/annotation-standard/SKILL.md` to standardize annotation workflow and conventions.
+
+### Changed
+
+- Updated `README.md` with rationale updates and new LLM assets/flowchart documentation.
+- Updated `init.mjs` to include deployment wiring for the new trunk changelog prompt and related README/documentation flow.
+- Updated `copilot/agents/tsfpp-annotate.agent.md` to align with the annotation standard.
+- Updated `copilot/agents/tsfpp-audit.agent.md` to include annotation-standard-aware checks.
+- Updated `copilot/agents/tsfpp-guarded-coding.agent.md` to route annotation work through the standard.
+
+## [1.3.5] - 2026-05-18
+
+### Changed
+
+- Fixed an `init.mjs` regression by restoring the main-clause wrapper to prevent dangling awaits and improve idempotent handling of existing files.
+- Updated `tdd` and `backfill-tests` agents to include a standards-enforcing self-review step.
+- Expanded `audit` agent checklist coverage with an extensive backfill of checklist items.
+
 ## [1.3.4] - 2026-05-18
 
 ### Changed

package/README.md

@@ -1,12 +1,103 @@
 # @tsfpp/agents
 
-GitHub Copilot agents, scoped instruction files, and Claude Code configuration for [TSF++](https://github.com/tsfpp/standard) projects.
+GitHub Copilot agents, scoped instruction files, skills, and Claude Code configuration for [TSF++](https://github.com/tsfpp/standard) projects.
 
-Installs a set of pre-built AI tooling into your project's `.github/` directory. Once installed, the agents are available in VS Code Copilot chat and the instruction files are injected automatically as context whenever you open a matching file.
+Installs a pre-built AI tooling layer into your project's `.github/` directory. Once installed, agents are available in VS Code Copilot chat, instruction files are injected automatically whenever a matching file is open, and skills are loaded on demand based on semantic relevance.
+
+---
+
+## Why this works
+
+TSF++ enforces a small, strict set of constraints: sum types with exhaustive dispatch, total functions via `Option` and `Result`, immutable records, no hidden effects, pipelines over imperative loops. These constraints exist because algebraic code is easier for a human to reason about locally — you can understand a function from its type alone, without tracing mutations or hidden control flow.
+
+The same properties that help humans happen to help language models significantly more. A codebase that never throws, never mutates, and always makes failure explicit in the type signature gives a model far less surface to hallucinate over. Exhaustive `switch` with `absurd` means the model cannot forget a variant. `Result<T, E>` means error paths are always visible in the return type. `pipe` makes data flow linear and readable in one pass.
+
+In practice: the agents generate fewer violations, the audit agent catches the ones that slip through, and the refactor agent can fix them mechanically because the fix is always the same shape. The standard makes the code predictable for humans — and predictable code is cheap for a model to generate correctly.
+
+---
+
+## Quickstart — greenfield project
+
+The fastest way to create a fully configured TSF++ project is the bootstrap script. It handles everything in one command:
+
+```sh
+bash <(curl -fsSL https://raw.githubusercontent.com/tsfpp/agents/main/bootstrap/tsfpp-bootstrap.sh) my-project
+cd my-project
+```
+
+Or, if you already have the script locally:
+
+```sh
+bash tsfpp-bootstrap.sh my-project
+cd my-project
+```
+
+Omit the project name to bootstrap in the current directory.
+
+### What the bootstrap script does
+
+| Step | What happens |
+|------|-------------|
+| 1 | `git init -b main` (skipped if a repo already exists) |
+| 2 | `pnpm init` |
+| 3 | Installs the full TSF++ ecosystem: `typescript`, `@tsfpp/standard`, `@tsfpp/tsconfig`, `@tsfpp/eslint-config`, `@tsfpp/prelude`, `@tsfpp/boundary`, `@tsfpp/agents` |
+| 4 | Writes `tsconfig.json` extending `@tsfpp/tsconfig/app` |
+| 5 | Writes `eslint.config.js` with the base TSF++ ESLint config |
+| 6 | Patches `package.json` with `type: module` and `typecheck`, `lint`, `check` scripts |
+| 7 | Creates `src/index.ts` with a getting-started comment |
+| 8 | Runs `node node_modules/@tsfpp/agents/init.mjs` — installs all agents, instructions, skills, and prompts |
+| 9 | Writes `.gitignore` (skipped if one already exists) |
+| 10 | Runs `pnpm exec husky install` to activate pre-commit hooks |
+
+### After bootstrapping
+
+The bootstrap script does not install `@tsfpp/workflow` (commit linting, release automation) or configure a git remote — those steps are intentionally separate and optional.
+
+**Add workflow tooling** (recommended for real projects):
+
+```sh
+pnpm add -D @tsfpp/workflow @commitlint/cli @commitlint/config-conventional husky
+node node_modules/@tsfpp/workflow/init.mjs
+```
+
+This installs:
+- `commitlint` with the Conventional Commits config
+- Husky hooks: `commit-msg` (lint) and `pre-commit` (typecheck + lint)
+- Release Please GitHub Actions workflow for automated semver releases and changelog generation
+
+**Push to GitHub** — use the `/trunk-init-repo` prompt in Copilot chat:
+
+```
+/trunk-init-repo
+```
+
+This handles the initial conventional commit, adds the remote, pushes to `main`, and ensures Husky hooks are active after the git init.
+
+### Complete sequence
+
+```sh
+# 1. Bootstrap
+bash tsfpp-bootstrap.sh my-project
+cd my-project
+
+# 2. Open in VS Code
+code .
+
+# 3. Add workflow tooling (optional but recommended)
+pnpm add -D @tsfpp/workflow @commitlint/cli @commitlint/config-conventional husky
+node node_modules/@tsfpp/workflow/init.mjs
+
+# 4. Push to GitHub — in Copilot chat:
+# /trunk-init-repo
+```
+
+From there, the full agent workflow is available immediately.
+
+---
 
 ## Prerequisites
 
-All `@tsfpp/*` packages must be installed in the consumer project. The agents reference their documentation from `node_modules/@tsfpp/*/` at runtime — this is what gives them stable, version-locked access to the standard and API surface without bundling duplicate content.
+All `@tsfpp/*` packages must be installed in the consumer project. The agents reference their documentation from `node_modules/@tsfpp/*/` at runtime — this gives them stable, version-locked access to the standard and API surface without bundling duplicate content.
 
 ```sh
 pnpm add -D \
@@ -17,37 +108,64 @@ pnpm add -D \
   @tsfpp/tsconfig
 ```
 
+---
+
 ## Installation
 
 ```sh
 pnpm add -D @tsfpp/agents
-pnpm dlx @tsfpp/agents
+node node_modules/@tsfpp/agents/init.mjs
 ```
 
 The `init` script copies all files into your project and prompts before overwriting anything that already exists. Commit the generated files — they are workspace configuration, not build artefacts.
 
-To re-run without reinstalling:
+### Non-interactive mode
+
+```sh
+node node_modules/@tsfpp/agents/init.mjs --yes
+```
+
+Copies all package-managed files without prompting. Skips `eslint.config.js` and `tsconfig.json` — those are workspace-owned and never touched automatically. Use this in `postinstall` scripts:
+
+```json
+{
+  "scripts": {
+    "postinstall": "node node_modules/@tsfpp/agents/init.mjs --yes"
+  }
+}
+```
+
+This ensures agents and instructions stay up to date with the installed package version on every `pnpm install`.
+
+### Re-run without reinstalling
 
 ```sh
 node node_modules/@tsfpp/agents/init.mjs
 ```
 
+---
+
 ## What gets installed
 
 ```
 .github/
-  copilot-instructions.md          ← always-on workspace context
+  copilot-instructions.md               ← always-on workspace context
   instructions/
-    tsfpp-base.instructions.md     ← applyTo: **/*.ts
-    tsfpp-prelude.instructions.md  ← applyTo: **/*.ts
-    tsfpp-react.instructions.md    ← applyTo: **/*.tsx
-    tsfpp-api.instructions.md      ← applyTo: routes, handlers, api dirs
+    tsfpp-base.instructions.md          ← applyTo: **/*.ts
+    tsfpp-prelude.instructions.md       ← applyTo: **/*.ts
+    tsfpp-api.instructions.md           ← applyTo: routes, handlers, api dirs
+    tsfpp-react.instructions.md         ← applyTo: **/*.tsx
+    tsfpp-testing.instructions.md       ← applyTo: **/*.{test,spec}.{ts,tsx}
+    trunk.instructions.md               ← applyTo: git workflow contexts
   agents/
+    tsfpp-tdd.agent.md
+    tsfpp-backfill-tests.agent.md
     tsfpp-guarded-coding.agent.md
     tsfpp-audit.agent.md
     tsfpp-refactor-engineer.agent.md
     tsfpp-annotate.agent.md
   prompts/
+    trunk-init-repo.prompt.md
     tsfpp-new-module.prompt.md
     tsfpp-boundary-review.prompt.md
   skills/
@@ -55,53 +173,116 @@ node node_modules/@tsfpp/agents/init.mjs
     prelude-api/SKILL.md
     boundary-api/SKILL.md
     react-coding-standard/SKILL.md
+    test-standard/SKILL.md
+    annotation-standard/SKILL.md
 .claude/
-  CLAUDE.md                          ← Claude Code project context
+  CLAUDE.md                             ← Claude Code project context
 ```
 
+---
+
 ## Agents
 
 | Agent | Purpose |
 |-------|---------|
-| `tsfpp-guarded-coding` | Writes TSF++-compliant TypeScript. Specify a layer at session start: `core` · `api` · `dal` · `react` · `cli`. Runs `tsc --noEmit` automatically after every file edit via a `PostToolUse` hook. |
-| `tsfpp-audit` | Audits a target path, package, or layer for TSF++ violations. Creates a structured markdown report in `docs/audits/` with per-slice checkboxes and a deviation register. |
-| `tsfpp-refactor-engineer` | Reads an audit report and fixes violations slice by slice. Updates the report as it goes. Includes per-rule fix strategies so it never resolves a violation by weakening a type. |
-| `tsfpp-annotate` | Adds missing JSDoc blocks, `DEVIATION(N.M)` comments, paired `eslint-disable` annotations, and structured code markers (`TODO`, `FIXME`, `HACK`, `NOTE`, `OPTIMIZE`, `BUG`, `XXX`). Never touches runtime code. |
+| `tsfpp-tdd` | The mandatory first step for new functionality. Writes a failing test suite that specifies the behaviour before any implementation exists. Verifies every test is red for assertion reasons, then hands off to `tsfpp-guarded-coding`. |
+| `tsfpp-backfill-tests` | Writes tests for existing code that has no coverage. Reads the implementation, derives the implicit contract, writes passing tests, and reports uncovered edge cases and implementation gaps. |
+| `tsfpp-guarded-coding` | Writes TSF++-compliant TypeScript. Infers the active layer from context (`core` · `api` · `dal` · `react` · `cli`); applies layer-specific constraints automatically. Refuses to start without failing tests in place. Runs `tsc --noEmit` after every file edit via a `PostToolUse` hook. |
+| `tsfpp-audit` | Audits a target path, package, or layer for TSF++ violations. Supports focus areas: `types` · `boundary` · `complexity` · `loc` · `annotations` · `security` · `react` · `data` · `prelude` · `test` · `all`. Creates a structured markdown report in `docs/audits/` with per-slice checkboxes and a deviation register. |
+| `tsfpp-refactor-engineer` | Reads an audit report and fixes violations slice by slice. Updates the report as it goes. Never resolves a violation by weakening a type. |
+| `tsfpp-annotate` | Adds missing JSDoc blocks, module headers, inline comments (invariants, rejected alternatives, external contracts), `DEVIATION(N.M)` comments, paired `eslint-disable` annotations, and structured code markers (`TODO`, `FIXME`, `HACK`, `NOTE`, `OPTIMIZE`, `BUG`, `XXX`). Never touches runtime code. Uses the `/annotation-standard` skill. |
+
+---
 
 ## Workflow
 
-The agents are designed to hand off to each other. After each agent completes, VS Code presents a handoff button to transition to the next step:
+The agents hand off to each other. Each handoff is opt-in — the developer reviews and approves each transition via the handoff buttons in Copilot chat.
+
+### New functionality (TDD first)
 
 ```
-tsfpp-guarded-coding
-  → tsfpp-audit          (verify what was written)
-    → tsfpp-refactor-engineer   (fix violations)
-      → tsfpp-annotate   (document the result)
-        → tsfpp-audit    (verify annotation coverage)
+tsfpp-tdd                  write failing tests
+  → tsfpp-guarded-coding   implement against the tests
+    → tsfpp-audit          verify compliance
+      → tsfpp-refactor-engineer   fix any violations
+        → tsfpp-annotate   document the result
 ```
 
-Handoffs are opt-in — the developer reviews and approves each transition.
+### Existing code without tests
+
+```
+tsfpp-backfill-tests       write passing tests from the existing contract
+  → tsfpp-audit            verify test compliance + coverage
+    → tsfpp-refactor-engineer   fix violations in tests or implementation
+```
+
+### Compliance audit only
+
+```
+tsfpp-audit                audit target with chosen focus
+  → tsfpp-refactor-engineer   fix violations
+    → tsfpp-annotate       document deviations and markers
+      → tsfpp-audit        re-audit to verify fixes
+```
+
+---
 
 ## Instruction files
 
-Instruction files are injected automatically by VS Code Copilot whenever a matching file is open. They require no explicit invocation.
+Instruction files are injected automatically by VS Code Copilot whenever a matching file is open. No explicit invocation required.
 
 | File | Active for | Content |
 |------|-----------|---------|
 | `tsfpp-base` | `**/*.ts` | Forbidden constructs, required patterns, size limits, ADT idioms, marker format |
-| `tsfpp-prelude` | `**/*.ts` | Full `@tsfpp/prelude` API surface: `Option`, `Result`, combinators, `pipe`, `absurd`, `Brand` |
-| `tsfpp-react` | `**/*.tsx` | Component shape, discriminated union state, TanStack Query, `useEffect` policy, memoisation |
-| `tsfpp-api` | Routes, handlers, API dirs | Handler shape, `@tsfpp/boundary` imports, Zod validation, status codes, security baseline |
+| `tsfpp-prelude` | `**/*.ts` | Full `@tsfpp/prelude` API: `Option`, `Result`, `ReadonlyMap`, `ReadonlySet`, `List`, combinators, record decoding |
+| `tsfpp-api` | Routes, handlers, api dirs | Handler shape, `@tsfpp/boundary` imports, Zod validation, middleware composition, status codes, security baseline |
+| `tsfpp-react` | `**/*.tsx` | Component shape, discriminated union state, state elimination ladder, `useEffect` policy, TanStack Query, RHF+Zod, cva/cn styling |
+| `tsfpp-testing` | `**/*.{test,spec}.{ts,tsx}` | AAA structure, factory usage, fast-check property tests, MSW, RTL query hierarchy, forbidden patterns |
+| `trunk` | Git workflow contexts | Conventional Commits, branch naming, PR discipline, trunk-based development rules |
+
+The workspace-level `copilot-instructions.md` is always active regardless of which file is open. It establishes the TSF++ axioms, the prelude-first principle, and the absolute non-negotiables.
+
+---
+
+## Skills
+
+Skills are loaded automatically by Copilot based on semantic match with what is being discussed. Unlike instruction files, skills are not file-scoped — they are injected into the context when the model determines they are relevant.
 
-The workspace-level `copilot-instructions.md` is always active regardless of which file is open. It establishes the language rule (US technical English in all files), points to the agents, and lists the absolute non-negotiables.
+| Skill | Loaded when |
+|-------|------------|
+| `coding-standard` | Writing or reviewing TypeScript; checking rules; auditing compliance |
+| `prelude-api` | Importing from or discussing `@tsfpp/prelude`; choosing between combinators |
+| `boundary-api` | Writing handlers; discussing HTTP error mapping, pagination, or middleware |
+| `react-coding-standard` | Writing React components, hooks, forms, or stores |
+| `test-standard` | Writing or reviewing test files; discussing coverage or test structure |
+| `annotation-standard` | Writing or reviewing any comment, JSDoc block, module header, code marker, or DEVIATION; discussing what to annotate and why |
+
+Skills are distilled from the full standard documents — concise enough to fit in the model's context without crowding out code.
+
+---
+
+## Prompts
+
+Reusable slash commands available in Copilot chat.
+
+| Prompt | Purpose |
+|--------|---------|
+| `/trunk-init-repo` | Initialises a git repository with `main` branch, `.gitignore`, an initial conventional commit, optional remote, and Husky hook activation. Run once after bootstrapping. |
+| `/trunk-changelog` | Inspects the current working tree diff, derives the correct conventional commit message, and appends a matching entry to the `## [Unreleased]` section of `CHANGELOG.md`. |
+| `/tsfpp-new-module` | Scaffolds a new TSF++ module with the correct file structure, barrel export, and JSDoc stubs. |
+| `/tsfpp-boundary-review` | Reviews an HTTP handler against the full `@tsfpp/boundary` contract. |
+
+---
 
 ## How agents reference the standard
 
-Each agent reads the TSF++ standards directly from `node_modules/@tsfpp/standard/` and the prelude API from `node_modules/@tsfpp/prelude/`. This means:
+Each agent reads TSF++ standards directly from `node_modules/@tsfpp/standard/spec/` and the prelude API from `node_modules/@tsfpp/prelude/` at runtime. This means:
+
+- The agent always enforces the version of the standard your project has installed.
+- Upgrading `@tsfpp/standard` automatically updates what the agents enforce — no changes to agent files required.
+- The agent files contain workflow logic, checklist structure, and layer-specific patterns — not rule content. Rule content lives in the standard packages.
 
-- The agent always uses the version of the standard your project has installed.
-- Upgrading `@tsfpp/standard` automatically updates what the agents enforce — no changes to the agent files required.
-- The agent files themselves contain workflow logic, not rule content.
+---
 
 ## Further reading
 
@@ -111,6 +292,8 @@ Each agent reads the TSF++ standards directly from `node_modules/@tsfpp/standard
 - [`@tsfpp/eslint-config`](https://github.com/tsfpp/eslint-config) — ESLint flat config
 - [`@tsfpp/tsconfig`](https://github.com/tsfpp/tsconfig) — TypeScript compiler presets
 
+---
+
 ## Release process
 
 Releases are automated with Release Please.
@@ -119,6 +302,8 @@ Releases are automated with Release Please.
 2. Release Please opens or updates a release PR on each merge to `main`.
 3. Merging the release PR publishes to npm, creates a GitHub release, and updates `CHANGELOG.md`.
 
+---
+
 ## License
 
 MIT