policy(strict): require description in package.json

[taras]

Motivation

AI agents have almost zero knowledge of @effectionx/* packages. When tested, agents couldn't recommend packages like @effectionx/process for process spawning or @effectionx/websocket for WebSocket connections.

Package descriptions in package.json are the primary source of truth for npm search and are being used by AI agent discovery systems like llms.txt.

Approach

1. Add strict policy (.policies/package-json-metadata.md) requiring all published packages to include a description field:

   • Single sentence, under 120 characters
   • No markdown, no trailing period
   • Written for npm search and AI discovery

2. Register policy in .policies/index.md as Strict (violations must be fixed before merge)

3. Update AGENTS.md to include description in package.json requirements

4. Add descriptions to all 23 published packages with concise, action-oriented descriptions:

   • @effectionx/process → "Spawn and manage child processes with structured concurrency"
   • @effectionx/websocket → "WebSocket client with stream-based message handling and automatic cleanup"
   • etc.

The .internal package is private and does not require a description per the policy.

Summary by CodeRabbit

• Documentation

  • Added a new package metadata policy specifying a required concise description format (single sentence, under 120 chars) with examples and verification guidance; docs updated to reference the policy.

• Chores

  • Added one-line description metadata across packages and updated versions to refresh published metadata for improved discoverability.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds a new strict Package.json Metadata policy and documentation, updates AGENTS.md to reference the policy, and adds concise top-level description fields (and minor version bumps in most cases) across many package.json manifests in the monorepo.

Changes

Cohort / File(s)	Summary
Policy docs .policies/index.md, .policies/package-json-metadata.md	Added a Policy Documents table entry and a new policy file enforcing a single-sentence, <120‑character description with examples, checklist, and verification guidance.
Agent documentation AGENTS.md	Updated Package.json Requirements to require the concise description field and reference the new package.json metadata policy.
Package manifests (metadata updates) bdd/package.json, chain/package.json, context-api/package.json, converge/package.json, effect-ts/package.json, fs/package.json, fx/package.json, jsonl-store/package.json, node/package.json, process/package.json, raf/package.json, scope-eval/package.json, signals/package.json, stream-helpers/package.json, stream-yaml/package.json, task-buffer/package.json, test-adapter/package.json, timebox/package.json, tinyexec/package.json, vitest/package.json, watch/package.json, websocket/package.json, worker/package.json	Added a concise top-level description to each listed package.json; most manifests also received a minor version bump. Changes are metadata-only.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• policy(strict): require description in package.json #151 — Implements the same strict package.json description policy and adds description fields to overlapping packages.

Poem

🐇 I nudge each package, small and bright,
One sentence snug, concise and light.
Versions tick with gentle cheer,
Descriptions clear for all who peer.
📦✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: introducing a strict policy requiring description fields in package.json files.
Description check	✅ Passed	The PR description fully addresses the template structure with clear Motivation and Approach sections, explaining the problem, solution, and all changes made.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch policy/package-json-description

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@effectionx/bdd

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/bdd@151

@effectionx/chain

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/chain@151

@effectionx/context-api

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/context-api@151

@effectionx/converge

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/converge@151

@effectionx/effect-ts

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/effect-ts@151

@effectionx/fs

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/fs@151

@effectionx/fx

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/fx@151

@effectionx/jsonl-store

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/jsonl-store@151

@effectionx/node

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/node@151

@effectionx/process

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/process@151

@effectionx/raf

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/raf@151

@effectionx/scope-eval

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/scope-eval@151

@effectionx/signals

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/signals@151

@effectionx/stream-helpers

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/stream-helpers@151

@effectionx/stream-yaml

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/stream-yaml@151

@effectionx/task-buffer

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/task-buffer@151

@effectionx/test-adapter

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/test-adapter@151

@effectionx/timebox

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/timebox@151

@effectionx/tinyexec

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/tinyexec@151

@effectionx/vitest

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/vitest@151

@effectionx/watch

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/watch@151

@effectionx/websocket

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/websocket@151

@effectionx/worker

npm i https://pkg.pr.new/thefrontside/effectionx/@effectionx/worker@151

commit: 0b21d67

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.policies/package-json-metadata.md:
- Around line 20-22: Update the policy text instances that read "No markdown
formatting" to capitalize the proper noun "Markdown" (i.e., change to "No
Markdown formatting"); locate and edit every occurrence of the phrase (including
the duplicate occurrence currently noted elsewhere) so the wording uses
"Markdown" consistently and maintain the existing punctuation, line length, and
other policy constraints.

🧹 Nitpick comments (1)

AGENTS.md (1)

90-94: Align wording with the strict policy to avoid ambiguity.
Line 93 currently omits “single sentence” and “no trailing period,” which are part of the strict policy. Consider aligning the phrasing to prevent inconsistent agent guidance.

Proposed wording tweak

- - `description`: Required — concise, under 120 chars, no markdown (see [Package.json Metadata policy](.policies/package-json-metadata.md))
+ - `description`: Required — single sentence, under 120 chars, no markdown, no trailing period (see [Package.json Metadata policy](.policies/package-json-metadata.md))