agentme 0.1.1

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -0,0 +1,89 @@
+# agentme-edr-003: JavaScript project tooling and structure
+
+## Context and Problem Statement
+
+JavaScript/TypeScript projects accumulate inconsistent tooling configurations, making onboarding, quality enforcement, and cross-project maintenance unnecessarily hard.
+
+What tooling and project structure should JavaScript/TypeScript projects follow to ensure consistency, quality, and ease of development?
+
+## Decision Outcome
+
+**Use pnpm, tsc, esbuild, eslint, and jest with a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
+
+Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
+
+### Implementation Details
+
+#### Tooling
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager — strict linking, workspace support, fast installs |
+| **tsc** | TypeScript compilation — type checking, declaration generation |
+| **esbuild** | Bundling — fast bundling for distribution or single-binary outputs |
+| **eslint** | Linting — code style and quality enforcement |
+| **jest** | Testing — unit and integration test runner |
+
+All commands are run exclusively through Makefiles, not through `package.json` scripts.
+
+#### ESLint
+
+Use `@stutzlab/eslint-config` as the base ESLint config. Use ESLint 9 flat config format (`lib/eslint.config.js`).
+
+#### Project structure
+
+```
+/                          # workspace root
+├── Makefile               # delegates build/lint/test to /lib and /examples
+├── README.md              # Quick Start first; used as npm registry page
+├── lib/                   # the published npm package
+│   ├── Makefile           # build, lint, test, publish targets
+│   ├── package.json       # package manifest
+│   ├── tsconfig.json      # TypeScript config
+│   ├── jest.config.js     # Jest config
+│   ├── eslint.config.js   # ESLint config (ESLint 9 flat config)
+│   └── src/               # all TypeScript source files
+│       ├── index.ts       # public API re-exports
+│       └── *.test.ts      # test files co-located with source
+└── examples/              # runnable usage examples
+    ├── Makefile           # build + test all examples in sequence
+    ├── usage-x/           # first example
+    │   └── package.json
+    └── usage-y/           # second example
+        └── package.json
+```
+
+The root `Makefile` delegates every target to `/lib` then `/examples` in sequence.
+
+#### lib/Makefile targets
+
+| Target | Description |
+|--------|-------------|
+| `install` | `pnpm install --frozen-lockfile` |
+| `build` | compile with `tsc`, strip test files from `dist/`, then `pnpm pack` for local use by examples |
+| `build-module` | compile with `tsc` only (no pack) |
+| `lint` | `pnpm exec eslint ./src` |
+| `lint-fix` | `pnpm exec eslint ./src --fix` |
+| `test` | `pnpm exec jest --verbose` |
+| `test-watch` | `pnpm exec jest --watch` |
+| `clean` | remove `node_modules/` and `dist/` |
+| `all` | `build lint test` |
+| `publish` | version-bump with `monotag`, then `npm publish --provenance` |
+
+#### lib/package.json key fields
+
+- `"main"`: `dist/index.js`
+- `"types"`: `dist/index.d.ts`
+- `"files"`: `["dist/**", "package.json", "README.md"]`
+- `"scripts"`: empty — all commands are driven by the Makefile
+
+#### examples/
+
+Each sub-folder under `examples/` is an independent package. The Makefile installs the locally built `.tgz` pack from `lib/dist/` so examples simulate real external usage.
+
+The examples folder MUST exist for any libraries and utilities that are published or have more than 500 lines of code
+
+### Related Skills
+
+- [001-create-javascript-project](skills/001-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
+

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -0,0 +1,141 @@
+# agentme-edr-010: Go project tooling and structure
+
+## Context and Problem Statement
+
+Go (Golang) projects often diverge in their module layout, tooling conventions, and build processes, making cross-project onboarding slow and CI pipelines hard to standardize. Without clear decisions on linting, testing, binary distribution, and package structure, teams repeatedly reinvent the same scaffolding.
+
+What tooling and project structure should Go projects follow to ensure consistency, quality, and ease of development?
+
+## Decision Outcome
+
+**Use the standard Go toolchain (`go build`, `go test`) with `golangci-lint` for linting, feature packages in subdirectories (no `internal/` by default), a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks, with the Go toolchain and related CLIs sourced from the repository's Mise-managed environment when the repository defines `.mise.toml`.**
+
+A predictable layout and minimal external tooling keep Go projects approachable, fast to build, and easy to distribute as cross-platform binaries.
+
+### Implementation Details
+
+#### Tooling
+
+| Tool | Purpose |
+|------|---------|
+| **go toolchain** | Compilation, testing, formatting (`go build`, `go test`, `go fmt`, `go vet`, `go mod`) |
+| **golangci-lint** | Linting — aggregates many linters in one fast run; configured via `.golangci.yml` |
+| **monotag** | Version tagging from git history for the `publish` target |
+
+All commands are run exclusively through the Makefile, never ad-hoc.
+When the repository has a root `.mise.toml`, `go`, `golangci-lint`, and any other Go-related CLIs used by the project **MUST** be pinned there and resolved from the Mise-managed environment rather than the host machine.
+Direct installation of project-required Go CLIs with `go install ...@latest` as a repair step is **NOT** allowed unless an XDR for that repository explicitly permits it.
+
+#### Project structure
+
+```
+/                              # project root (single Go module)
+├── Makefile                   # build, lint, test, publish, and utility targets
+├── go.mod                     # module declaration (github.com/<owner>/<project>)
+├── go.sum                     # locked dependency checksums
+├── main.go                    # binary entry point — argument dispatch only, no logic
+├── .golangci.yml              # golangci-lint configuration
+├── .gitignore
+├── README.md
+├── <feature-a>/               # domain package (e.g. ownership/, changes/, utils/)
+│   ├── *.go                   # business logic
+│   └── *_test.go              # unit tests co-located with source
+├── <feature-b>/
+│   └── ...
+└── cli/                       # CLI wiring — ties flags to domain packages
+    ├── <feature-a>/
+    │   └── *.go
+    └── <feature-b>/
+        └── *.go
+```
+
+**Key layout rules:**
+
+- One Go module per project (`go.mod` at the project root). In a monorepo, each Go project has its own `go.mod` in its subdirectory. No nested modules within a single project unless explicitly justified.
+- `main.go` is solely an argument dispatcher — it reads `os.Args[1]` and delegates to a `cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
+- Business logic lives in named feature packages at the root (e.g., `ownership/`, `changes/`, `utils/`). These packages are importable and testable without any CLI concerns.
+- `cli/` packages own flag parsing, output formatting, and the wiring between flags and domain functions. No business logic lives in `cli/`.
+- Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
+
+#### go.mod
+
+- Module path: `github.com/<owner>/<project>` (or the relevant VCS path for the project)
+- Use the latest stable Go version (e.g. `go 1.24`).
+- Separate `require` blocks: direct dependencies first, then `// indirect` dependencies.
+- If the repository uses Mise, the Go version declared in `go.mod` and the Go version pinned in `.mise.toml` **MUST** stay aligned.
+
+#### Makefile targets
+
+| Target | Description |
+|--------|-------------|
+| `all` | Default; runs `build lint test` in sequence |
+| `build` | `go mod download && go build -o dist/<binary>` |
+| `build-all` | Cross-compile for all target platforms (darwin/linux/windows × amd64/arm64) |
+| `build-arch-os` | Compile for a specific `OS` and `ARCH` environment variable pair; output to `dist/${OS}-${ARCH}/<binary>` |
+| `install` | `go mod download` |
+| `lint` | `golangci-lint run ./...` |
+| `lint-fix` | `golangci-lint run --fix ./...` |
+| `test` | `go test -cover ./...` — runs all tests with coverage |
+| `test-unit` | `go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
+| `coverage` | `go tool cover -func ./coverage.out` — displays coverage summary |
+| `clean` | Remove `dist/` and any coverage files |
+| `start` | `go run ./ <default-args>` — launch the binary locally for dev use |
+| `publish` | Tag with `monotag`, then push tag + binaries to GitHub Releases |
+
+When the repository uses Mise, the intended invocation pattern is:
+
+```sh
+mise install
+mise exec -- make build
+mise exec -- make test
+mise exec -- make lint
+```
+
+Using `make build`, `make test`, or `make lint` from an already activated Mise shell is equivalent.
+
+#### Cross-platform binary distribution
+
+When the project produces a CLI binary for end-users:
+
+- Build separate binaries for: `darwin/amd64`, `darwin/arm64`, `linux/amd64`, `linux/arm64`, `windows/amd64`.
+- Use `GOOS`, `GOARCH`, and `CGO_ENABLED=0` to produce fully static binaries.
+- Store outputs under `dist/${OS}-${ARCH}/<binary-name>`.
+- Optionally wrap binaries in npm packages (one package per platform) for distribution via `npx`. Each npm package contains only the binary for its platform; a meta-package with a `bin/` entry that delegates to the correct platform package is added at the root of the npm folder.
+
+#### Testing
+
+- Tests are co-located with source: `<feature>/<file>_test.go`.
+- Use `github.com/stretchr/testify` (`assert`, `require`) for test assertions.
+- Run all tests: `go test -cover ./...`
+- Benchmarks: `go test -bench . -benchmem -count 20`
+- Integration or slow tests: guard with `//go:build integration` and skip in unit runs via `-tags=unit`.
+
+#### Linting
+
+Configure `.golangci.yml` with at minimum:
+
+```yaml
+linters:
+  enable:
+    - errcheck
+    - govet
+    - staticcheck
+    - unused
+    - gosimple
+    - ineffassign
+    - typecheck
+run:
+  timeout: 5m
+```
+
+#### Logging
+
+Use `github.com/sirupsen/logrus` for structured logging. Set the log level from a `--verbose` CLI flag, defaulting to `false` / `WarnLevel`. Do not use `fmt.Println` for diagnostic output.
+
+#### CLI flag parsing
+
+Use the standard library `flag` package for CLI flags. Each `cli/<feature>` package defines its own `FlagSet`, parses it from `os.Args[2:]`, and calls the corresponding domain function.
+
+### Related Skills
+
+- [003-create-golang-project](skills/003-create-golang-project/SKILL.md) — scaffolds a new Go project following this structure

package/.xdrs/agentme/edrs/application/skills/001-create-javascript-project/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: 001-create-javascript-project
+description: >
+  Scaffolds the initial boilerplate structure for a JavaScript/TypeScript library project following
+  the standard tooling and layout defined in _core-edr-003. Activate this skill when the user
+  asks to create, scaffold, or initialize a new JavaScript or TypeScript library project, npm
+  package, or similar project structure.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+compatibility: JavaScript/TypeScript, Node.js 18+
+---
+
+## Overview
+
+Creates a complete JavaScript/TypeScript library project from scratch. The layout separates
+library source (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level
+Makefiles. Boilerplate is derived from the [npmdata](https://github.com/flaviostutz/npmdata)
+project.
+
+Related EDR: [agentme-edr-003](../../003-javascript-project-tooling.md)
+
+## Instructions
+
+### Phase 1: Gather information
+
+1. Ask for (or infer from context):
+   - **Package name** (npm-compatible, e.g. `my-lib`)
+   - **Short description** (one sentence)
+   - **Author** name or GitHub username
+   - **Node.js version** (default: `24`)
+   - **GitHub repo URL** (optional, for `package.json` fields)
+2. Confirm the target directory (default: current workspace root).
+
+---
+
+### Phase 2: Create root files
+
+**`./Makefile`**
+
+Delegates every make target to `/lib` then `/examples` in sequence:
+
+```makefile
+SHELL := /bin/bash
+%:
+	@echo ''
+	@echo '>>> Running /lib:$@...'
+	@cd lib && make $@
+	@echo ''
+	@echo '>>> Running /examples:$@...'
+	@cd examples && STAGE=dev make $@
+
+publish:
+	cd lib && make publish
+
+prepare:
+	@echo "Run 'nvm use; corepack enable'"
+```
+
+**`./.nvmrc`**
+
+```
+24
+```
+(Replace `24` with the chosen Node.js version.)
+
+**`./.gitignore`**
+
+```
+node_modules/
+dist/
+*.tgz
+.npmdata
+```
+
+---
+
+### Phase 3: Create `lib/`
+
+**`lib/src/index.ts`** — public API entry point:
+
+```typescript
+export const hello = (name: string): string => {
+  return `Hello, ${name}!`;
+};
+```
+
+**`lib/src/index.test.ts`** — co-located unit test:
+
+```typescript
+import { hello } from './index';
+
+describe('hello', () => {
+  it('should return a greeting', () => {
+    expect(hello('world')).toBe('Hello, world!');
+  });
+});
+```
+
+**`lib/Makefile`**:
+
+```makefile
+SHELL := /bin/bash
+
+build: install
+	@rm -rf dist
+	pnpm exec tsc --outDir dist
+	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
+	@# Create pack for use by examples to simulate real external usage
+	pnpm pack --pack-destination dist
+
+build-module: install
+	@rm -rf dist
+	pnpm exec tsc --outDir dist
+	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
+
+lint:
+	pnpm exec eslint ./src --ext .ts
+
+lint-fix:
+	pnpm exec eslint . --ext .ts --fix
+
+test-watch:
+	pnpm exec jest --watch
+
+test:
+	pnpm exec jest --verbose
+
+clean:
+	rm -rf node_modules
+	rm -rf dist
+
+all: build lint test
+
+install:
+	pnpm install --frozen-lockfile --config.dedupe-peer-dependents=false
+
+publish:
+	npx -y monotag@1.26.0 current --bump-action=latest --prefix=
+	@VERSION=$$(node -p "require('./package.json').version"); \
+	if echo "$$VERSION" | grep -q '-'; then \
+		TAG=$$(echo "$$VERSION" | sed 's/[0-9]*\.[0-9]*\.[0-9]*-\([a-zA-Z][a-zA-Z0-9]*\).*/\1/'); \
+		echo "Prerelease version $$VERSION detected, publishing with --tag $$TAG"; \
+		npm publish --no-git-checks --provenance --tag "$$TAG"; \
+	else \
+		npm publish --no-git-checks --provenance; \
+	fi
+```
+
+**`lib/package.json`** (replace `[package-name]`, `[description]`, `[author]`, `[owner]`, `[repo]`):
+
+```json
+{
+  "name": "[package-name]",
+  "version": "0.0.1",
+  "description": "[description]",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "package.json",
+    "README.md"
+  ],
+  "packageManager": "pnpm@8.9.0",
+  "scripts": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/[owner]/[repo].git"
+  },
+  "author": "[author]",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/[owner]/[repo]/issues"
+  },
+  "homepage": "https://github.com/[owner]/[repo]#readme",
+  "devDependencies": {
+    "@babel/preset-typescript": "^7.21.0",
+    "@stutzlab/eslint-config": "^3.2.1",
+    "@tsconfig/node24": "^24.0.0",
+    "@types/jest": "^29.5.0",
+    "esbuild": "^0.20.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+**`lib/tsconfig.json`**:
+
+```json
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+**`lib/jest.config.js`**:
+
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
+};
+```
+
+**`lib/eslint.config.js`** (ESLint 9 flat config format):
+
+```js
+import baseConfig from '@stutzlab/eslint-config';
+
+export default [
+  ...baseConfig,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.json'],
+        tsconfigRootDir: process.cwd(),
+      },
+    },
+  },
+];
+```
+
+---
+
+### Phase 4: Create `examples/`
+
+**`examples/Makefile`** (replace `[package-name]`):
+
+```makefile
+SHELL := /bin/bash
+%:
+	@echo "Unknown target: $@. Ignoring"
+
+build: install
+	@echo "Examples built"
+
+install:
+	# Replace the lib dependency with the locally built pack
+	pnpm add [package-name]@file:../lib/dist/[package-name]-0.0.1.tgz
+	pnpm install
+
+test:
+	@echo "Running example tests..."
+	cd usage-basic && node index.js
+
+all: build test
+```
+
+**`examples/usage-basic/package.json`** (replace `[package-name]`):
+
+```json
+{
+  "name": "usage-basic",
+  "version": "1.0.0",
+  "description": "Basic usage example for [package-name]",
+  "type": "module",
+  "scripts": {},
+  "dependencies": {
+    "[package-name]": "file:../../lib/dist/[package-name]-0.0.1.tgz"
+  }
+}
+```
+
+**`examples/usage-basic/index.js`**:
+
+```javascript
+import { hello } from '[package-name]';
+
+const result = hello('world');
+console.log(result);
+// expected output: Hello, world!
+```
+
+---
+
+### Phase 5: Create `README.md`
+
+Quick Start must appear at the top — it is rendered first on the npm registry page.
+
+```markdown
+# [package-name]
+
+[description]
+
+## Quick Start
+
+\`\`\`bash
+pnpm add [package-name]
+\`\`\`
+
+\`\`\`typescript
+import { hello } from '[package-name]';
+
+const greeting = hello('world');
+console.log(greeting); // Hello, world!
+\`\`\`
+
+## Installation
+
+\`\`\`bash
+npm install [package-name]
+# or
+pnpm add [package-name]
+\`\`\`
+
+## Examples
+
+See the [examples/](examples/) folder for complete runnable examples.
+
+## License
+
+MIT
+```
+
+---
+
+### Phase 6: Verify
+
+Review all created files and confirm:
+
+- [ ] Root `Makefile` delegates to both `lib/` and `examples/`
+- [ ] `lib/src/index.ts` exports at least one symbol
+- [ ] `lib/src/index.test.ts` has at least one passing test
+- [ ] `lib/package.json` has `main`, `types`, and `files` set correctly
+- [ ] `README.md` starts with Quick Start containing a code example
+- [ ] All `[package-name]` placeholders are replaced with the actual name
+- [ ] Structure matches the layout in [_core-edr-003](../../003-javascript-project-tooling.md)
+
+## Examples
+
+**User:** "Create a new TypeScript library project called `retry-client`"
+
+**Agent action:** Gathers: name=`retry-client`, default Node.js 24, then creates:
+- `./Makefile`, `./.nvmrc`, `./.gitignore`
+- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.js`
+- `examples/Makefile`, `examples/usage-basic/package.json`, `examples/usage-basic/index.js`
+- `README.md` (Quick Start first)
+
+All `[package-name]` replaced with `retry-client`.
+
+## Edge Cases
+
+- **Existing files** — skip creation; adapt references to the existing structure
+- **Different Node.js version** — update `.nvmrc` and `tsconfig.json` `extends` (e.g. `@tsconfig/node22`)
+- **CLI tool** — add `"bin": "dist/main.js"` to `package.json` and create `lib/src/main.ts` as the CLI entry point; add `esbuild` bundle target in `lib/Makefile`
+- **No examples needed** — omit the `examples/` directory; remove the `examples` delegation from root `Makefile`
+- **Binary bundling (Lambda/browser)** — add an esbuild step to `lib/Makefile`: `pnpm exec esbuild src/main.ts --bundle --platform=node --outfile=dist/bundle.js`