@produck/agent-toolkit 0.1.5 → 0.2.0

package/publish-assets/instructions/produck/15-produck-workspace.instructions.md

@@ -0,0 +1,293 @@
+---
+applyTo: '**'
+---
+
+<!-- managed-by: @produck/agent-toolkit -->
+<!-- source: .github/distribution/produck/15-produck-workspace.instructions.md -->
+
+# Workspace Shared Configuration Guide
+
+## Overview
+
+The Produck monorepo provides unified configuration across all packages for consistency and ease of maintenance.
+
+## Distribution classification
+
+This document is maintained directly as a downstream-distributable source.
+
+- Authoritative path:
+  `.github/distribution/produck/15-produck-workspace.instructions.md`
+
+## Shared Configurations
+
+### 1. ESLint Configuration (`eslint.config.mjs`)
+
+**Location:** Root `eslint.config.mjs`
+
+**Applies to:** All JavaScript, TypeScript files
+
+**Rules:**
+
+- Indentation: 2 spaces (error)
+- Quotes: Single quotes (error)
+- Line endings: Unix (LF) (error)
+- Semicolons: Always required (error)
+- Trailing commas: Always in multiline (error)
+- No inline config allowed: `noInlineConfig: true`
+
+**Usage in packages:**
+
+```javascript
+// packages/my-package/eslint.config.mjs
+import rootConfig from '../../eslint.config.mjs';
+
+export default [
+  ...rootConfig,
+  // Package-specific overrides here
+];
+```
+
+### 2. TypeScript Configuration (`tsconfig.json`)
+
+**Location:** Root `tsconfig.json`
+
+**Applies to:** All TypeScript packages
+
+**Key settings:**
+
+- Target: ES2022
+- Strict mode: enabled
+- Module resolution: node
+- Source maps: enabled
+- Declaration files: generated
+
+**Usage in packages:**
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}
+```
+
+### 3. Prettier Configuration (`.prettierrc`)
+
+**Location:** Root `.prettierrc`
+
+**Applies to:** All source files
+
+**Rules:**
+
+- Print width: 100 characters
+- Tab width: 2 spaces
+- Single quotes: true
+- Trailing commas: es5
+- Arrow parens: always
+- Semicolons: true
+
+**Ignored files:** `.prettierignore`
+
+### 4. Git Ignore Configuration (`.gitignore`)
+
+**Location:** Root `.gitignore` (centralized, no package-level overrides)
+
+**Applies to:** All files in the monorepo
+
+**Strategy:** Single source of truth at repository root per monorepo convention
+
+**Rules:**
+
+- Dependencies: `node_modules/`, npm logs
+- Coverage: `coverage/`, `.nyc_output/`
+- Environment: `.env`, `.env.local`, `.env.*.local`
+- Build: `dist/`, `build/`, `out/`, `*.tsbuildinfo`
+- OS/Editor: `.DS_Store`, `Thumbs.db`, `.vscode/settings.json`, `.idea/`
+- Temporary: `logs/`, `tmp/`, `temp/`
+- Generated: `*.gen`, `*.ign` (organization team extensions)
+
+**Why centralized?**
+
+- All packages automatically inherit root patterns
+- Single maintenance point
+- No package-level overrides allowed
+- Per organization baseline: keep ignore rules centralized at repository root whenever possible
+
+## Root Workspace Scripts
+
+### Verification & Quality
+
+```bash
+# Type check all packages
+npm run type-check
+
+# Format check without writing
+npm run format:check
+
+# Format and write
+npm run format
+
+# Lint (requires root eslint.config.mjs)
+npm run lint
+
+# Run all package tests
+npm run test
+
+# Check coverage across packages
+npm run coverage
+```
+
+### Package-Specific Commands
+
+```bash
+# Verify toolkit package
+npm run toolkit:verify
+
+# Verify eslint-rules package
+npm run eslint-rules:verify
+
+# Check package distributions
+npm run toolkit:pack-check
+npm run eslint-rules:pack-check
+```
+
+## Package Integration
+
+### Adding a New Package
+
+1. Create `packages/my-package/` directory
+2. Create `packages/my-package/package.json` with workspace configuration
+3. Inherit root configs:
+   - ESLint: extend `../../eslint.config.mjs`
+   - TypeScript: extend `../../tsconfig.json`
+   - Prettier: uses root `.prettierrc` automatically
+
+### Package-Level Overrides
+
+Each package can extend/override shared config:
+
+**ESLint example:**
+
+```javascript
+import rootConfig from '../../eslint.config.mjs';
+import onlyWarn from 'eslint-plugin-only-warn';
+
+export default [
+  ...rootConfig,
+  {
+    plugins: { 'only-warn': onlyWarn },
+    rules: {
+      'custom-rule': 'warn', // package-specific override
+    },
+  },
+];
+```
+
+## .editorconfig
+
+**Location:** Root `.editorconfig`
+
+Applies to all editors supporting EditorConfig (VSCode, Vim, Sublime, etc.):
+
+- Charset: utf-8
+- Indent: 2 spaces
+- Line endings: Unix (LF)
+- Trim trailing whitespace
+
+## Dependencies
+
+### Shared devDependencies (Root)
+
+- `@eslint/config-helpers`: ESLint configuration utilities
+- `@eslint/js`: ESLint recommended config for JavaScript
+- `eslint`: Core linter
+- `typescript-eslint`: TypeScript linting support
+- `globals`: Global variables (browser, node)
+- `prettier`: Code formatter
+- `typescript`: TypeScript compiler
+- `@types/node`: Node.js type definitions
+
+### Peer Dependencies (Packages)
+
+Each package declares peer dependencies for features it uses:
+
+```json
+{
+  "peerDependencies": {
+    "eslint": ">=10.3.0",
+    "@eslint/config-helpers": ">=0.6.0"
+  }
+}
+```
+
+## CI/CD Integration
+
+Root scripts are designed for CI pipelines:
+
+```bash
+# Pre-commit checks
+npm run format:check
+npm run type-check
+npm run lint
+
+# Testing
+npm run test
+npm run coverage
+
+# Package verification
+npm run toolkit:verify
+npm run eslint-rules:verify
+```
+
+## Best Practices
+
+1. **Always extend shared config** instead of duplicating
+2. **Use workspace lint/format scripts** for consistency
+3. **Keep package-level overrides minimal** - justify in comments
+4. **Update root config** when org-wide rule changes needed
+5. **Test configuration changes** with all packages before committing
+6. **Do NOT add package-level `.gitignore`** - only root `.gitignore` is allowed; all packages inherit from it
+
+## Troubleshooting
+
+### ESLint complains about missing peer deps
+
+```bash
+# Install missing peer dependencies
+npm install
+```
+
+### Prettier conflicts with ESLint
+
+Root `.prettierrc` and `eslint.config.mjs` are synchronized. If conflict occurs:
+
+1. Check both configs have matching rules
+2. Run `npm run format` first, then `npm run lint`
+
+### TypeScript includes too many files
+
+Update `tsconfig.json` `include` and `exclude` patterns:
+
+```json
+{
+  "include": ["packages/*/src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+### Files are being tracked by git that should be ignored
+
+Verify `.gitignore` patterns:
+
+```bash
+# Check if file matches any gitignore pattern
+git check-ignore -v <file-or-directory>
+
+# Update only root .gitignore - no package-level .gitignore allowed
+# All packages inherit patterns from root
+```
+
+Do NOT create package-level `.gitignore` files - they will be removed per organization policy.

package/publish-assets/instructions/produck/20-produck-commit.instructions.md

@@ -0,0 +1,175 @@
+---
+applyTo: '**'
+---
+
+<!-- managed-by: @produck/agent-toolkit -->
+<!-- source: .github/distribution/produck/20-produck-commit.instructions.md -->
+
+# Commit Convention
+
+Repositories in the `produck` organization use a bracketed TAG style for commit
+messages.
+
+## Format
+
+Use this format:
+
+- `[TAG] summary`
+
+Multi-line commit message rule:
+
+- Every non-empty line in the commit message must start with `[TAG]`.
+- Empty lines are not allowed in commit message body.
+- Do not use untagged bullet lines in commit message body.
+- If body details are needed, repeat tagged lines instead of raw bullets.
+- `summary` cannot appear as a standalone untagged line.
+
+Monorepo format (required for multi-package repositories):
+
+- Package/workspace labels appear as **section headers** followed by a colon
+  (format: `package-name:` or `@scope/package:`).
+- All lines under a package header belong to that package.
+- Every line under a package header must start with `[TAG]`.
+- No empty lines between tagged lines within a package section.
+- Multiple packages follow the same pattern (each with its own header).
+
+Example monorepo format:
+
+```
+foo:
+[FIX] race condition in auth handler
+[ADD] <test>: cover edge case for concurrent login
+bar:
+[REFACTOR] <docs>: rewrite installation guide
+```
+
+Standalone repository format:
+
+- Do not use package/workspace section headers.
+- Write commit messages directly as `[TAG] summary`.
+- All tagged lines belong to the repository globally.
+
+Allowed tags (fixed whitelist):
+
+- `[INIT]`
+- `[ADD]`
+- `[REMOVE]`
+- `[FIX]`
+- `[REFACTOR]`
+- `[UPGRADE]`
+- `[PUBLISH]`
+
+Legacy-to-canonical mapping (for migration):
+
+- `[ADDED]` -> `[ADD]`
+- `[REMOVED]` -> `[REMOVE]`
+- `[FIXED]` -> `[FIX]`
+
+When using this style:
+
+- `TAG` must be uppercase and must be one of the allowed tags above.
+- Summary must be in English.
+- Keep summaries specific and behavior-oriented.
+- Summary may include a target noun prefix to express content domain.
+- Mention concrete areas when useful (route, endpoint, helper, file, test,
+  constraint).
+- Prefer one clear tagged change per line when writing grouped summaries.
+- `[REFACTOR]` implies potentially breaking updates and should explicitly
+  describe impact.
+- Special rule for `[UPGRADE]`: use `[UPGRADE] deps` for pure dependency
+  upgrades.
+- If `[UPGRADE]` also includes IFF artifacts or IPC-related artifacts/calls, the
+  summary must explicitly name the updated artifact/call.
+- Special rule for `[PUBLISH]`: use `[PUBLISH]` for release and package
+  publishing commits managed by lerna or similar tools. No target required.
+
+Summary target extension (optional):
+
+- Format: `[TAG] <target>: <summary>`
+- Allowed targets (fixed whitelist):
+  - `docs`: documentation content, guides, comments, and usage notes
+  - `test`: test cases, fixtures, assertions, and test tooling
+  - `ci`: continuous integration workflows, pipeline steps, and automation jobs
+  - `deps`: dependency declarations, lockfiles, and dependency management scripts
+  - `api`: externally visible interfaces, route contracts, and client/server API
+    behavior
+  - `schema`: data model definitions, migration schemas, and validation schema
+    changes
+  - `infra`: infrastructure and environment provisioning/configuration
+  - `fmt`: code formatting, style, and linter configuration changes
+- When target syntax is used, `target` must be one of the allowed values above.
+- Target must be wrapped in angle brackets (`<target>`) to distinguish it from
+  namespace-like identifiers inside summary text.
+- Targets are nouns in summary context, not tags.
+
+## Examples
+
+- `[FIX] race conditions in createTeam/acceptInvitation/acceptRequest by
+wrapping checks and writes in one transaction`
+- `[FIX] <infra>: enforce node-first execution`
+- `[FIX] <infra>: remove repo-local ignore for transient logs`
+- `[FIX] <infra>: add policy-repo exception for local agent output`
+- `[ADD] shared helper src/Web/Student/Router/Team/membership.mjs for
+student-side team mutation routes`
+- `[REFACTOR] remove c8 ignore on Screenshot.mjs response.ok (covered by
+integration test)`
+- `[INIT] initialize @tjuamt/eer-score-field-ai-kitchen debug tool`
+- `[REMOVE] deprecated score-field prompt template`
+- `[UPGRADE] deps`
+- `[ADD] <docs>: onboarding section for monorepo mode`
+- `[FIX] <test>: stabilize screenshot upload retry assertion`
+- `[REFACTOR] <ci>: split lint and test jobs for faster feedback`
+
+Monorepo examples:
+
+```
+foo:
+[FIX] a
+[FIX] b
+[FIX] c
+```
+
+```
+core:
+[ADD] <api>: new user authentication endpoint
+[REFACTOR] <test>: restructure session management tests
+utils:
+[UPGRADE] <deps>: update lodash to v4.17.21
+[FIX] <docs>: clarify error handling in README
+```
+
+## Avoid
+
+Avoid vague or low-signal messages such as:
+
+- `[ADD] update things`
+- `[FIX] issue`
+- `[UPGRADE] dependencies` when artifact/call updates exist but are not named
+- `[ADD] docs: ...` (target syntax without angle brackets)
+- `[ADD] <feature>: ...` (target outside allowed whitelist)
+- `[added] ...` (non-uppercase tag)
+- `[CHANGED] ...` (tag outside whitelist)
+- `- remove old script` (untagged body line)
+- `summary without tag` (untagged standalone line)
+- empty lines between tagged lines
+- Monorepo mistakes:
+  - `foo: [FIX] a` (package header and tag on same line)
+  - `@produck/foo: [FIX] a` (package name in every tag line instead of
+    section header)
+  - `foo:\n\n[FIX] a` (empty line after package header)
+  - `foo:` without any tagged lines below (orphaned section header)
+
+## Validation
+
+Use the local validator before commit:
+
+- `npm exec --package=@produck/agent-toolkit@latest agent-toolkit
+validate-commit-msg --file <message-file>`
+
+If validation fails, fix the message and rerun until it passes.
+
+## Notes
+
+- Keep the summary concise and specific.
+- Prefer imperative phrasing.
+- This document does not restrict PR title format.

package/templates/help/sync-instructions.txt

@@ -1,8 +1,11 @@
 Usage:
   agent-toolkit sync-instructions [--cwd <dir>] [--out <file>]
-    [--source <file>] [--force] [--dry-run]
+    [--source <file-or-dir>] [--force] [--prune] [--dry-run]
 
 Behavior:
-  - Writes organization instruction entrypoint template to target file.
-  - Defaults to <cwd>/.instructions.md when --out is not provided.
-  - If target exists, command fails unless --force is set.
+  - Syncs one or multiple .instructions.md files to target path.
+  - Defaults to <cwd>/.github/instructions/produck when --out is not provided.
+  - If --source is a directory, all *.instructions.md files in that directory are synced.
+  - If --source is omitted, built-in namespaced assets are used.
+  - Existing changed files require --force.
+  - --prune deletes unmanaged leftovers only when file contains managed marker.

package/templates/user-space-bootstrap.md

@@ -0,0 +1,14 @@
+# Repository AI Instructions
+
+This repository uses organization baseline instructions from:
+
+- {{NAMESPACE_GLOB}}
+
+Repository-specific rules should be written in this file.
+Keep organization baseline rules in the produck namespace files above.
+
+Recommended usage:
+
+- Add local constraints and exceptions here.
+- Do not copy organization baseline content into this file.
+- Keep this file focused on repository-only behavior.

package/templates/default.instructions.md

@@ -1,21 +0,0 @@
-# Organization Collaboration Instructions
-
-This repository follows organization-level AI and engineering rules.
-
-## Required Rules
-
-- Commit message format must follow bracketed TAG policy.
-- Keep root .editorconfig aligned with organization baseline:
-  - If missing, create from organization sample.
-  - If present, add missing required keys only (minimal merge).
-- Repository owners generate and own eslint.config.mjs.
-- AI must not rewrite full eslint config; only add missing
-  @produck/eslint-rules integration as minimal patch.
-- Repository-specific ESLint overrides must layer on top of
-  @produck/eslint-rules.
-
-## References
-
-- docs/ai-collaboration.md
-- docs/commit-convention.md
-- docs/nodejs-initialization.md