agentme 0.5.0 → 0.7.0

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

@@ -13,12 +13,13 @@ 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 [filedist](https://github.com/flaviostutz/filedist)
+Creates a complete JavaScript/TypeScript library project from scratch. The layout keeps the
+published package self-contained in its module root (`lib/`), places runnable consumer examples in
+the sibling `examples/` folder, redirects persistent caches into `.cache/`, and uses Makefiles as
+the only entry points. Boilerplate is derived from the [filedist](https://github.com/flaviostutz/filedist)
 project.
 
-Related EDR: [agentme-edr-003](../../003-javascript-project-tooling.md)
+Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -38,7 +39,7 @@ Related EDR: [agentme-edr-003](../../003-javascript-project-tooling.md)
 
 **`./Makefile`**
 
-Delegates every make target to `/lib` then `/examples` in sequence:
+Delegates every make target to `/lib` then `/examples` in sequence. Child Makefiles own the actual `mise exec -- <tool>` calls:
 
 ```makefile
 SHELL := /bin/bash
@@ -46,13 +47,13 @@ MISE := mise exec --
 %:
 	@echo ''
 	@echo '>>> Running /lib:$@...'
-  @$(MISE) $(MAKE) -C lib $@
+  @$(MAKE) -C lib $@
 	@echo ''
 	@echo '>>> Running /examples:$@...'
-  @STAGE=dev $(MISE) $(MAKE) -C examples $@
+  @STAGE=dev $(MAKE) -C examples $@
 
 publish:
-  @$(MISE) $(MAKE) -C lib publish
+  @$(MAKE) -C lib publish
 
 setup:
   mise install
@@ -72,6 +73,7 @@ pnpm = "10.14.0"
 ```
 node_modules/
 dist/
+.cache/
 *.tgz
 .filedist
 ```
@@ -105,24 +107,29 @@ describe('hello', () => {
 ```makefile
 SHELL := /bin/bash
 MISE := mise exec --
+CACHE_DIR := .cache
 
 build: install
 	@rm -rf dist
-  $(MISE) pnpm exec tsc --outDir dist
+  @mkdir -p $(CACHE_DIR)/tsc
+  $(MISE) pnpm exec tsc --incremental --tsBuildInfoFile $(CACHE_DIR)/tsc/tsconfig.tsbuildinfo --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
   $(MISE) pnpm pack --pack-destination dist
 
 build-module: install
 	@rm -rf dist
-  $(MISE) pnpm exec tsc --outDir dist
+  @mkdir -p $(CACHE_DIR)/tsc
+  $(MISE) pnpm exec tsc --incremental --tsBuildInfoFile $(CACHE_DIR)/tsc/tsconfig.tsbuildinfo --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 
 lint:
-  $(MISE) pnpm exec eslint ./src
+  @mkdir -p $(CACHE_DIR)/eslint
+  $(MISE) pnpm exec eslint ./src --cache --cache-location $(CACHE_DIR)/eslint/.eslintcache
 
 lint-fix:
-  $(MISE) pnpm exec eslint ./src --fix
+  @mkdir -p $(CACHE_DIR)/eslint
+  $(MISE) pnpm exec eslint ./src --fix --cache --cache-location $(CACHE_DIR)/eslint/.eslintcache
 
 test-watch:
   $(MISE) pnpm exec jest --watch
@@ -133,6 +140,7 @@ test:
 clean:
 	rm -rf node_modules
 	rm -rf dist
+  rm -rf .cache
 
 all: build lint test
 
@@ -223,6 +231,8 @@ Use this single tsconfig for both build and type-aware linting. Keep `*.test.ts`
 module.exports = {
   testEnvironment: 'node',
   testMatch: ['**/*.test.ts'],
+  cacheDirectory: '<rootDir>/.cache/jest',
+  coverageDirectory: '<rootDir>/.cache/coverage',
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
   transform: {
     '^.+\\.tsx?$': [
@@ -323,7 +333,29 @@ console.log(result);
 
 ---
 
-### Phase 5: Create `README.md`
+### Phase 5: Create `README.md` and `lib/README.md`
+
+Keep the repository README focused on the workspace and the module README focused on consumers of
+the published package.
+
+**`README.md`**
+
+```markdown
+# [package-name]
+
+[description]
+
+## Getting Started
+
+```bash
+mise install
+make test
+```
+
+The published module lives in `lib/` and runnable consumer examples live in `examples/`.
+```
+
+**`lib/README.md`**
 
 Quick Start must appear at the top — it is rendered first on the npm registry page.
 
@@ -334,28 +366,37 @@ Quick Start must appear at the top — it is rendered first on the npm registry
 
 ## Quick Start
 
-\`\`\`bash
+```bash
 pnpm add [package-name]
-\`\`\`
+```
 
-\`\`\`typescript
+```typescript
 import { hello } from '[package-name]';
 
 const greeting = hello('world');
 console.log(greeting); // Hello, world!
-\`\`\`
+```
 
 ## Installation
 
-\`\`\`bash
+```bash
 npm install [package-name]
 # or
 pnpm add [package-name]
-\`\`\`
+```
 
 ## Examples
 
-See the [examples/](examples/) folder for complete runnable examples.
+See the sibling `examples/` folder for complete runnable examples that consume the packed artifact
+from `lib/dist/`.
+
+## Development
+
+```bash
+make build
+make lint
+make test
+```
 
 ## License
 
@@ -369,12 +410,13 @@ MIT
 Review all created files and confirm:
 
 - [ ] Root `Makefile` delegates to both `lib/` and `examples/`
+- [ ] `.gitignore` ignores `dist/` and `.cache/`
 - [ ] `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
 - [ ] `lib/tsconfig.json` includes co-located `src/**/*.test.ts` files for ESLint type-aware parsing
 - [ ] `lib/eslint.config.mjs` points `parserOptions.project` to `tsconfig.json`
-- [ ] `README.md` starts with Quick Start containing a code example
+- [ ] `lib/README.md` starts with Quick Start and ends with module development commands
 - [ ] All `[package-name]` placeholders are replaced with the actual name
 - [ ] Structure matches the layout in [agentme-edr-003](../../003-javascript-project-tooling.md)
 
@@ -384,9 +426,9 @@ Review all created files and confirm:
 
 **Agent action:** Gathers: name=`retry-client`, default Node.js 24, then creates:
 - `./Makefile`, `./.mise.toml`, `./.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.mjs`
+- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/README.md`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.mjs`
 - `examples/Makefile`, `examples/usage-basic/package.json`, `examples/usage-basic/index.js`
-- `README.md` (Quick Start first)
+- `README.md` (workspace overview)
 
 All `[package-name]` replaced with `retry-client`.
 

package/.xdrs/agentme/edrs/application/skills/003-create-golang-project/SKILL.md

@@ -12,9 +12,9 @@ compatibility: Go 1.21+
 
 ## Overview
 
-Creates a complete Go CLI project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md). Business logic lives in named feature packages; CLI wiring lives in `cli/<feature>/`; `main.go` is a thin dispatcher. The project builds cross-platform static binaries via a Makefile.
+Creates a complete Go CLI project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md). Business logic lives in named feature packages; CLI wiring lives in `cli/<feature>/`; `main.go` is a thin dispatcher. The module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
 
-Related EDR: [agentme-edr-010](../../010-golang-project-tooling.md)
+Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -35,6 +35,16 @@ Ask for (or infer from context):
 
 ### Phase 2: Create root files
 
+**`./.mise.toml`** (replace `[go-version]` and `[golangci-lint-version]`):
+
+```toml
+[tools]
+go = "[go-version]"
+golangci-lint = "[golangci-lint-version]"
+```
+
+Pin any additional project CLIs used by the Makefile here as well. Use an explicit `golangci-lint` version rather than `latest`.
+
 **`go.mod`** (replace `[module]`, `[go-version]`):
 
 ```
@@ -81,14 +91,24 @@ func main() {
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 
 BINARY := [binary]
+CACHE_DIR := .cache
+export GOCACHE := $(abspath $(CACHE_DIR)/go-build)
+export GOMODCACHE := $(abspath $(CACHE_DIR)/go-mod)
+export GOLANGCI_LINT_CACHE := $(abspath $(CACHE_DIR)/golangci-lint)
 
 all: build lint test
 
+setup:
+	mise install
+	$(MAKE) install
+
 build: install
 	@mkdir -p dist
-	go build -o dist/$(BINARY) .
+	@mkdir -p $(GOCACHE) $(GOMODCACHE)
+	$(MISE) go build -o dist/$(BINARY) .
 
 build-all: build-arch-os-darwin-amd64 build-arch-os-darwin-arm64 build-arch-os-linux-amd64 build-arch-os-linux-arm64 build-arch-os-windows-amd64
 	@echo "All platform builds complete"
@@ -113,35 +133,37 @@ build-arch-os:
 	@if [ "${ARCH}" == "" ]; then echo "ENV ARCH is required"; exit 1; fi
 	@echo "Compiling $(BINARY) for ${OS}-${ARCH}..."
 	@mkdir -p dist/${OS}-${ARCH}
-	go mod download
-	GOOS=${OS} GOARCH=${ARCH} CGO_ENABLED=0 go build -a -o dist/${OS}-${ARCH}/$(BINARY) .
+	@mkdir -p $(GOCACHE) $(GOMODCACHE)
+	$(MISE) go mod download
+	GOOS=${OS} GOARCH=${ARCH} CGO_ENABLED=0 $(MISE) go build -a -o dist/${OS}-${ARCH}/$(BINARY) .
 	@echo "Done"
 
 install:
-	go mod download
+	$(MISE) go mod download
 
 lint:
-	golangci-lint run ./...
+	$(MISE) golangci-lint run ./...
 
 lint-fix:
-	golangci-lint run --fix ./...
+	$(MISE) golangci-lint run --fix ./...
 
 test:
-	go test -cover ./...
+	$(MISE) go test -cover ./...
 
 test-coverage:
-	go test -coverprofile=coverage.out ./...
-	go tool cover -func coverage.out
+	@mkdir -p $(CACHE_DIR)
+	$(MISE) go test -coverprofile=$(CACHE_DIR)/coverage.out ./...
+	$(MISE) go tool cover -func $(CACHE_DIR)/coverage.out
 
 benchmark:
-	go test -bench . -benchmem -count 5 ./...
+	$(MISE) go test -bench . -benchmem -count 5 ./...
 
 clean:
 	rm -rf dist
-	rm -f coverage.out
+	rm -rf .cache
 
 start:
-	go run ./ [subcommand]
+	$(MISE) go run ./ [subcommand]
 ```
 
 **`.golangci.yml`**:
@@ -164,6 +186,7 @@ run:
 
 ```
 dist/
+.cache/
 coverage.out
 *.pprof
 .DS_Store
@@ -182,10 +205,11 @@ coverage.out
 
 ## Development
 
-    make build    # compile binary to dist/
-    make lint     # run golangci-lint
-    make test     # run tests with coverage
-    make start    # run locally with default args
+	make setup
+	make build    # compile binary to dist/
+	make lint     # run golangci-lint with cache in .cache/
+	make test     # run tests with coverage artifacts in .cache/
+	make start    # run locally with default args
 ```
 
 ---
@@ -292,7 +316,7 @@ func Run(args []string) {
 After creating all files, run the following in the project root:
 
 ```bash
-go mod tidy
+make setup
 make all
 ```
 
@@ -306,6 +330,8 @@ Fix any compile or lint errors before finishing.
 - Business logic only in `[feature]/` packages — no flag parsing, no `fmt.Println` for diagnostics.
 - `cli/[feature]/` owns flags, output, and calls domain. No logic here beyond reading flags and printing results.
 - All tests co-located (`*_test.go` next to the file under test).
+- Use `tests_integration/` for integration flows and `tests_benchmark/` when benchmarks need dedicated harnesses or datasets.
 - Log with `logrus`; never use `fmt.Println` for diagnostic/debug output.
-- All development tasks go through `make` targets — never run `go` directly for routine ops.
+- All development tasks go through `make` targets. The Makefile recipes call `mise exec -- go ...` and related tools directly.
 - Do not create an `internal/` package unless explicitly justified (importability is preferred).
+- If the project is a reusable library, place consumer examples in a sibling `examples/` folder outside the module root and keep them on the public module import path.