agentme 0.1.1

package/.xdrs/agentme/edrs/devops/008-common-targets.md

@@ -0,0 +1,207 @@
+# agentme-edr-008: Common development script names
+
+## Context and Problem Statement
+
+Software projects use a wide variety of commands and tooling to perform the same fundamental tasks — building, testing, linting, and deploying. This diversity is amplified across language ecosystems, meaning developers must re-learn project-specific conventions every time they switch contexts. CI pipelines suffer from the same fragmentation, each one requiring bespoke scripts.
+
+What standard set of command names and conventions should projects adopt so that any developer or CI pipeline can immediately operate on any project without needing to read documentation first?
+
+## Decision Outcome
+
+**Every project must expose its development actions using a defined set of standardized script names, grouped by lifecycle phase. These names apply regardless of the script runner used — Makefile, npm scripts, shell scripts, or any other tool — so that `build`, `test`, `lint`, and related commands work predictably across all projects and languages.**
+
+Standardizing script names removes the cognitive overhead of learning per-project conventions, makes CI pipelines reusable across projects, and gives new developers an immediately operational entry point. The names are the contract; the underlying runner is an implementation detail.
+
+### Implementation Details
+
+#### 1. Every project MUST have a root-level entry point exposing the standard script names
+
+The project root must contain a single authoritative entry point — a `Makefile`, `package.json` scripts section, a shell wrapper, or equivalent — that exposes the standard target names defined in rule 2. Developers and CI pipelines must invoke actions through this entry point exclusively, never by calling underlying tools directly.
+
+**Preferred runner: Makefile.** A `Makefile` is the default recommended choice because it is language-agnostic, universally available, and provides a consistent invocation syntax (`make <target>`) across all ecosystems.
+
+**Alternative runners** are acceptable when a Makefile is not practical for the project's ecosystem:
+
+| Runner | Invocation example | When appropriate |
+|--------|--------------------|------------------|
+| Makefile | `make build` | Default; recommended for all projects |
+| npm scripts | `npm run build` | Pure Node.js/frontend projects without a Makefile |
+| Shell script | `./dev.sh build` | Projects where `make` is unavailable or impractical |
+| Other (Taskfile, just, etc.) | `task build` | When agreed upon at the project or org level |
+
+Whichever runner is chosen, the **target names** defined in rule 2 must be used unchanged. The runner is an implementation detail; the names are the shared contract.
+
+*Why:* A single entry point means developers and CI pipelines use near-identical commands regardless of the underlying language or tooling. Any tooling change is then contained to the entry-point file and does not require updating CI pipelines or developer documentation.
+
+---
+
+#### 2. Standard script groups and names
+
+Scripts are organized into five lifecycle groups. Projects must use these names regardless of the script runner in use. Extensions are allowed (see rule 4) but the core names must not be repurposed.
+
+##### Developer group
+
+| Script | Purpose |
+|--------|---------|
+| `setup` | Install any tools required on the developer machine (e.g., nvm, brew, python, golang). Typically run once per project checkout. In CI, tooling is usually pre-provisioned via runner images or workflow steps instead. |
+| `all` | Alias that runs `build`, `lint`, and `test` in sequence. Must be the default target (i.e., running `make` or the runner with no arguments invokes `all`). Used by developers as a fast pre-push check to verify the software meets minimum quality standards in one command. |
+| `clean` | Remove all temporary or generated files created during build, lint, or test (e.g., `node_modules`, virtual environments, compiled binaries, generated files). Used both locally and in CI for a clean slate. |
+| `dev` | Run the software locally for development (e.g., start a Node.js API server, open a Jupyter notebook, launch a React dev server). May have debugging tools, verbose logging, or hot reloading features enabled. |
+| `run` | Run the software in production mode (e.g., start a compiled binary, launch a production server). No debugging or development-only features should be enabled. |
+| `update-lockfile` | Update the dependency lockfile to reflect the latest resolved versions of all dependencies. |
+
+##### Build group
+
+| Script | Purpose |
+|--------|---------|
+| `build` | Install dependencies, compile, and package the software. The full `install → compile → package` workflow. |
+| `install` | Download and install all project dependencies. Assumes the language runtime is already available (installed via `setup`). |
+| `compile` | Compile source files into binaries or transpiled output. Assumes dependencies are already installed. |
+| `package` | Assemble a distributable package from compiled files and other resources. Use the `VERSION` environment variable to set the package version explicitly. |
+| `bump` | Automatically upgrade dependencies to the latest version that satisfies the semver range declared in the dependency manifest (e.g., `package.json`, `go.mod`, `pyproject.toml`). Does not widen or change the declared range — only resolves to the highest compatible version within it. After bumping, updates the lockfile and stages the changes. Useful for routine dependency maintenance without risking breaking semver contracts. |
+
+##### Lint group
+
+| Script | Purpose |
+|--------|---------|
+| `lint` | Run **all static quality checks** outside of tests. This MUST include: code formatting validation, code style enforcement, code smell detection, static analysis, dependency audits for known CVEs, security vulnerability scans (e.g., SAST), and project/configuration structure checks. All checks must be non-destructive (read-only); fixes are handled by `lint-fix`. |
+| `lint-fix` | Automatically fix linting and formatting issues where possible. || `lint-format` | *(Optional)* Check code formatting only (e.g., Prettier, gofmt, Black). |
+##### Test group
+
+| Script | Purpose |
+|--------|---------|
+| `test` | Run **all tests** required for the project. This MUST include unit tests (with coverage enforcement — the build MUST fail if coverage thresholds are not met) and integration/end-to-end tests. Normally delegates to `test-unit` and `test-integration` in sequence. |
+| `test-unit` | Run unit tests only, including coverage report generation and coverage threshold enforcement. |
+| `test-integration` | *(Optional)* Run integration and end-to-end tests only. Projects without integration tests may omit this target. |
+| `test-smoke` | *(Optional)* Run a fast, minimal subset of tests to verify the software is basically functional. Useful as a post-deploy health check. |
+
+##### Release group
+
+| Script | Purpose |
+|--------|---------|
+| `release` | Determine the next version (e.g., via semantic versioning and git tags), generate changelogs and release notes, tag the repository, and create a release artifact. Normally invokes `docgen`. |
+| `docgen` | Generate documentation (API docs, static sites, changelogs, example outputs). |
+| `publish` | Upload the versioned package to the appropriate registry (npm, PyPI, DockerHub, GitHub Releases, blob storage, etc.). Depends on `release` and `package` having been run first. |
+| `deploy` | Provision the software on a running environment. Use the `STAGE` environment variable to select the target environment (e.g., `STAGE=dev make deploy`). |
+| `undeploy` | Deactivate or remove the software from an environment. Use the `STAGE` environment variable in the same way as `deploy`. Useful for tearing down ephemeral PR environments. |
+
+---
+
+#### 3. Standard environment variables
+
+Two environment variables have defined semantics and must be used consistently.
+
+| Variable | Purpose |
+|----------|---------|
+| `STAGE` | Identifies the runtime environment. Format: `[prefix][-variant]`. Common prefixes: `dev`, `tst`, `acc`, `prd`. Examples: `dev`, `dev-pr123`, `tst`, `prd-blue`. May be required by any target that is environment-aware (build, lint, deploy, etc.). |
+| `VERSION` | Sets the explicit version used during packaging and deployment. Used when there is no automatic version-tagging utility, or to override it. |
+
+---
+
+#### 4. Extending scripts with prefixes
+
+Projects may add custom scripts beyond the standard set. Custom scripts must be named by prefixing a standard script name with a descriptive qualifier, keeping the naming intuitive and consistent with the group it belongs to.
+
+**Examples:**
+
+```
+build-dev         # prepare a build specifically for STAGE=dev
+build-docker      # build a Docker image with the application
+test-smoke        # run a fast subset of unit tests on critical paths
+test-examples     # run the examples/ folder as integration tests
+publish-npm       # publish to the npm registry specifically
+publish-docker    # publish a Docker image
+run-docker        # run the application inside a Docker container
+start-debugger    # launch the software with a visual debugger attached
+deploy-infra      # deploy only the infrastructure layer
+```
+
+The prefix convention ensures developers can infer the purpose of any script without documentation.
+
+---
+
+#### 5. Monorepo usage
+
+In a monorepo, each module has its own `Makefile` with its own `build`, `lint`, `test`, and `deploy` targets scoped to that module. Parent-level Makefiles (at the application or repo root) delegate to module Makefiles in sequence.
+
+```makefile
+# root Makefile — delegates to all modules
+build:
+	$(MAKE) -C module-a build
+	$(MAKE) -C module-b build
+
+test:
+	$(MAKE) -C module-a test
+	$(MAKE) -C module-b test
+```
+
+A developer can run `make test` at the repo root to test everything, or `cd module-a && make test` to test a single module. Both must work.
+
+**Reference:** See [agentme-edr-005](005-monorepo-structure.md) for the full monorepo layout convention.
+
+---
+
+#### 6. Quick-reference — commands a developer can always rely on
+
+Any project following this EDR supports the following actions. Examples show Makefile syntax; substitute your project's runner (e.g., `npm run build`, `./dev.sh build`) if a Makefile is not used.
+
+```sh
+# install required development tools
+make setup
+
+# build the software (install deps, compile, package)
+make build
+
+# run all tests (unit + integration)
+make test
+
+# check code formatting, style, code smells, CVE audits, security scans, and project structure
+make lint
+
+# auto-fix lint/formatting issues
+make lint-fix
+
+# run the software in dev mode (may have hot reload, debug tools enabled, verbose logging etc)
+make dev
+
+# run the software in production mode
+make run
+
+# generate next version, changelogs, and tag the repo; then package
+make release package
+
+# publish the release to a registry (e.g., npm, PyPI)
+make publish
+
+# deploy to the dev environment
+STAGE=dev make deploy
+
+# remove all temporary/generated files
+make clean
+
+# run build + lint + test in one shot (pre-push check)
+make all
+```
+
+**Equivalent examples for npm scripts and shell:**
+
+```sh
+# npm scripts (package.json)
+npm run build
+npm run test
+npm run lint
+STAGE=dev npm run deploy
+
+# shell wrapper
+./dev.sh build
+./dev.sh test
+STAGE=dev ./dev.sh deploy
+```
+
+## Considered Options
+
+* (REJECTED) **Language-native entry points only** - Use `npm run`, `python -m`, `go run` etc. directly as the standard without a unifying name convention
+  * Reason: Ties CI pipelines and developer muscle memory to language-specific tooling; breaks the abstraction when the underlying tool changes; target names vary per ecosystem
+
+* (CHOSEN) **Standardized script names, runner-agnostic** - A common, language-agnostic command vocabulary that must be used regardless of whether the runner is a Makefile, npm scripts, a shell wrapper, or another tool; with Makefile as the preferred default
+  * Reason: Separating the names (the contract) from the runner (the implementation) gives every developer and CI pipeline a predictable interface while allowing each project to choose the most practical runner for its ecosystem.

package/.xdrs/agentme/edrs/devops/skills/002-monorepo-setup/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: 002-monorepo-setup
+description: >
+  Step-by-step instructions for setting up and scaffolding a new monorepo following the standard
+  layout, naming conventions, Makefiles, Mise tooling, and README requirements defined in
+  agentme-edr-005. Activate this skill when the user asks to create, initialize, or set up a
+  monorepo, add a new application or module to an existing monorepo, or verify that a monorepo
+  complies with the standard structure.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../005-monorepo-structure.md):
+top-level application folders, a shared library area, Mise-managed tooling, and Makefiles at every
+level so any contributor can build, lint, and test any part of the monorepo with a single,
+predictable command.
+
+Related EDR: [agentme-edr-005](../../005-monorepo-structure.md)
+
+## Instructions
+
+### Phase 1: Gather information
+
+1. Ask for (or infer from context):
+   - **Applications** — names and short descriptions of the top-level applications to scaffold.
+   - **Modules** — modules inside each application (e.g., `renderer`, `dataloader`, `cli`).
+   - **Primary language(s)** — Go, Python, TypeScript, etc., to choose the right build commands.
+   - **Tool versions** — versions to pin in `.mise.toml` (compilers, runtimes, CLI tools).
+2. Confirm the target directory (default: current workspace root).
+
+---
+
+### Phase 2: Create root-level files
+
+#### `.mise.toml`
+
+Pin all required tool versions. Example for a Go + Node.js monorepo:
+
+```toml
+[tools]
+go = "1.22"
+node = "24"
+golangci-lint = "1.57"
+```
+
+#### Root `Makefile`
+
+Coordinates `build`, `lint`, and `test` across all applications. Also exposes a `setup` target.
+
+```makefile
+.PHONY: build lint test setup
+
+APPS := <app1> <app2>   # replace with actual application names
+
+build:
+	$(foreach app,$(APPS),$(MAKE) -C $(app) build &&) true
+
+lint:
+	$(foreach app,$(APPS),$(MAKE) -C $(app) lint &&) true
+
+test:
+	$(foreach app,$(APPS),$(MAKE) -C $(app) test &&) true
+
+setup:
+	@echo "Install Mise: https://mise.jdx.dev/getting-started.html"
+	@echo "Then run: mise install"
+	@echo "See README.md for full setup instructions."
+```
+
+#### Root `README.md`
+
+Must include four sections:
+
+```markdown
+# <Monorepo Name>
+
+## Overview
+<What this monorepo contains and its high-level structure.>
+
+## Machine setup
+1. Install [Mise](https://mise.jdx.dev/getting-started.html).
+2. Clone the repository and run `mise install`.
+3. <Any OS-level prerequisites.>
+
+## Quickstart
+<Instructions to run at least one project locally as a concrete working example.>
+
+## Repository map
+| Folder              | Description                        |
+|---------------------|------------------------------------|
+| `shared/`           | Libraries and scripts shared across all apps |
+| `<app1>/`           | <Short description of app1>        |
+| `<app2>/`           | <Short description of app2>        |
+```
+
+---
+
+### Phase 3: Create the `shared/` area
+
+```
+shared/
+├── libs/       # Reusable libraries consumed by applications
+└── scripts/    # Build/CI/dev scripts used across applications
+```
+
+Create these folders; populate only if shared content already exists.
+
+---
+
+### Phase 4: Scaffold each application
+
+For each application:
+
+1. **Create the application folder** using lowercase, hyphen-separated names (e.g., `graph-visualizer`).
+
+2. **Create `<app>/README.md`** with the four required sections:
+
+   ```markdown
+   # <Application Name>
+
+   ## Purpose
+   <What this application does and why it exists.>
+
+   ## Architecture overview
+   | Module        | Description                        |
+   |---------------|------------------------------------|
+   | `<module1>/`  | <What it does and what it produces>|
+
+   ## How to build
+   Run `make build` from this folder or from the repository root.
+
+   ## How to run
+   <Minimal working example.>
+   ```
+
+3. **Create `<app>/Makefile`** that delegates to each module:
+
+   ```makefile
+   .PHONY: build lint test
+
+   MODULES := <module1> <module2>   # replace with actual module names
+
+   build:
+   	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) build &&) true
+
+   lint:
+   	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) lint &&) true
+
+   test:
+   	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) test &&) true
+   ```
+
+4. **Create `<app>/shared/`** — leave empty if no cross-module shared code exists yet.
+
+---
+
+### Phase 5: Scaffold each module
+
+For each module inside an application:
+
+1. **Create the module folder** using lowercase, hyphen-separated names (e.g., `data-loader`).
+
+2. **Create `<app>/<module>/Makefile`** with the three required targets, adapted to the module's language:
+
+   **Go:**
+   ```makefile
+   .PHONY: build lint test
+
+   build:
+   	go build ./...
+
+   lint:
+   	golangci-lint run ./...
+
+   test:
+   	go test ./... -cover
+   ```
+
+   **Node.js / TypeScript:**
+   ```makefile
+   .PHONY: build lint test
+
+   build:
+   	npm run build
+
+   lint:
+   	npm run lint
+
+   test:
+   	npm test
+   ```
+
+   **Python:**
+   ```makefile
+   .PHONY: build lint test
+
+   build:
+   	pip install -e .
+
+   lint:
+   	ruff check .
+
+   test:
+   	pytest
+   ```
+
+3. **Add source files** appropriate to the language, placing them inside the module folder.
+
+---
+
+### Phase 6: Verify and report
+
+After scaffolding, run the following checks and fix any issues:
+
+- `make build` at the repository root succeeds.
+- `make lint` at the repository root passes.
+- `make test` at the repository root passes.
+- All folder and file names are lowercase and use hyphens.
+- Every application folder has a `README.md` covering all four required sections.
+- A `.mise.toml` exists at the repository root with all required tool versions pinned.
+
+---
+
+## Examples
+
+### Example: adding a new `pcb-devices` application with a `firmware` module (Go)
+
+```
+pcb-devices/
+├── README.md
+├── Makefile
+├── shared/
+└── firmware/
+    └── Makefile
+```
+
+`pcb-devices/Makefile`:
+```makefile
+.PHONY: build lint test
+MODULES := firmware
+build:
+	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) build &&) true
+lint:
+	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) lint &&) true
+test:
+	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) test &&) true
+```
+
+`pcb-devices/firmware/Makefile`:
+```makefile
+.PHONY: build lint test
+build:
+	go build ./...
+lint:
+	golangci-lint run ./...
+test:
+	go test ./... -cover
+```
+
+---
+
+## Edge Cases
+
+- **Cross-application dependency requested:** Refuse and suggest publishing the shared code as a library in `shared/libs/` instead.
+- **Module with no compilable output (e.g., pure scripts):** Still create the Makefile; `build` can be a no-op (`@true`) but the target must exist.
+- **Language not listed above:** Mirror the pattern — `build` produces an artifact, `lint` runs static analysis, `test` runs tests. Adapt commands to the actual toolchain.
+- **Existing files:** Never overwrite existing `README.md` or `Makefile` files without user confirmation. Diff and propose additions instead.

package/.xdrs/agentme/edrs/index.md

@@ -0,0 +1,41 @@
+# agentme EDRs Index
+
+Engineering decisions specific to the agentme project: a curated library of XDRs and skills encoding best practices for AI coding agents.
+
+Propose changes via pull request. All changes must be verified for clarity and non-conflict before merging.
+
+## Related scope indexes
+
+- [_core EDRs Index](../../_core/edrs/index.md) - Cross-business general standards (overridden by this scope where conflicts are documented)
+
+XDRs in scopes listed last override the ones listed first.
+
+## Principles
+
+Foundational standards, principles, and guidelines.
+
+- [agentme-edr-002](principles/002-coding-best-practices.md) - **Coding best practices**
+- [agentme-edr-004](principles/004-unit-test-requirements.md) - **Unit test requirements**
+- [agentme-edr-007](principles/007-project-quality-standards.md) - **Project quality standards**
+- [agentme-edr-009](principles/009-error-handling.md) - **Error handling**
+
+## Application
+
+Language and framework-specific tooling and project structure.
+
+- [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
+- [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
+
+## Devops
+
+Repository structure, build conventions, and CI/CD pipelines.
+
+- [agentme-edr-005](devops/005-monorepo-structure.md) - **Monorepo structure** *(includes skill: [002-monorepo-setup](devops/skills/002-monorepo-setup/SKILL.md))*
+- [agentme-edr-006](devops/006-github-pipelines.md) - **GitHub CI/CD pipelines**
+- [agentme-edr-008](devops/008-common-targets.md) - **Common development script names**
+
+## Observability
+
+Health, metrics, logging, and monitoring standards.
+
+- [agentme-edr-011](observability/011-service-health-check-endpoint.md) - **Service health check endpoint**

package/.xdrs/agentme/edrs/observability/011-service-health-check-endpoint.md

@@ -0,0 +1,78 @@
+# agentme-edr-011: Service health check endpoint
+
+## Context and Problem Statement
+
+Services in distributed environments need standardized health endpoints so load balancers, orchestrators, and monitoring systems can determine availability and readiness. Without consistent health checks, infrastructure cannot make informed routing decisions and operational teams lack visibility into dependency status.
+
+How should services expose their health status and validate operational readiness?
+
+## Decision Outcome
+
+**Standardized `/health` endpoint with dependency validation**
+
+All services must expose a `GET /health` endpoint that validates external dependencies using read-only operations and returns structured status with appropriate HTTP codes.
+
+### Implementation Details
+
+**Endpoint contract:**
+
+| Aspect | Requirement |
+|--------|-------------|
+| Path | `/health` |
+| Method | `GET` |
+| Authentication | None (publicly accessible) |
+| Timeout | 30 seconds maximum |
+
+**HTTP status codes:**
+
+| Code | State | Infrastructure action |
+|------|-------|-----------------------|
+| `200` | `OK` | Route traffic normally |
+| `210` | `WARNING` | Route normally, trigger alerts |
+| `503` | `ERROR` | Remove from load balancer rotation |
+
+**Response body:**
+```json
+{ "health": "OK|WARNING|ERROR", "latencyMs": 156, "message": "All dependencies operational" }
+```
+
+- `health` (required): overall state — `OK`, `WARNING`, or `ERROR`
+- `latencyMs` (required): total milliseconds to run all checks
+- `message` (required): human-readable summary; must never expose credentials, internal IPs, or stack traces
+
+**Dependency validation rules:**
+
+- Check all external dependencies (databases, downstream APIs, queues, caches) using read-only operations (e.g., `SELECT 1`, lightweight GET, connection ping)
+- Never execute write operations or create side effects
+- `OK`: all dependencies healthy within expected thresholds
+- `WARNING`: non-critical dependency degraded, or elevated but acceptable response times
+- `ERROR`: critical dependency unavailable or service unable to process requests
+
+**Implementation guidelines:**
+
+- Run dependency checks in parallel to minimize latency
+- Cache check results for 5–10 seconds to avoid overwhelming dependencies
+- Apply per-dependency timeouts (5–10 seconds each)
+- Use circuit breaker patterns to fail fast on known-bad dependencies
+- Log failures for debugging; avoid excessive logging on every successful check
+
+**Integration points:**
+
+- Load balancers: 30 s interval, 2 consecutive failures to mark unhealthy, 2 successes to restore
+- Container orchestrators (ECS, Kubernetes): use `/health` for liveness and readiness probes
+- Monitoring: periodic polling with alerts on `210` and `503` responses
+- CI/CD: poll `/health` to confirm deployment success
+
+## Considered Options
+
+* (REJECTED) **No health checks** — detect failures through request errors
+  * Reason: Reactive; customer-visible failures occur before detection; no degraded-state visibility
+* (REJECTED) **Simple ping returning 200** — no dependency validation
+  * Reason: A service can appear healthy while critical dependencies are down
+* (CHOSEN) **Standardized `/health` with dependency validation** — single aggregated endpoint
+  * Reason: Actionable health info without exposing internals; enables infrastructure automation; balances operational visibility with security
+
+## References
+
+- [Health Check Response Format for HTTP APIs (IETF draft)](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check)
+- [AWS ALB Health Checks](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-health-checks.html)