agentme 0.1.1

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

@@ -0,0 +1,311 @@
+---
+name: 003-create-golang-project
+description: >
+  Scaffolds the initial boilerplate structure for a Go (Golang) CLI or library project following
+  the standard tooling and layout defined in agentme-edr-010. Activate this skill when the user
+  asks to create, scaffold, or initialize a new Go project, CLI binary, or Go module.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+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.
+
+Related EDR: [agentme-edr-010](../../010-golang-project-tooling.md)
+
+## Instructions
+
+### Phase 1: Gather information
+
+Ask for (or infer from context):
+
+- **Module name** — Go module path, e.g. `github.com/<owner>/<project>` (in a monorepo this is typically the workspace module path plus the project subdirectory)
+- **Binary name** — name of the produced CLI binary (default: project name)
+- **Short description** — one sentence
+- **Author** name or GitHub username
+- **Go version** — default `1.24`
+- **First feature package name** — the first domain package to scaffold (e.g. `analyze`, `parse`, `report`)
+- **First CLI subcommand name** — typically matches the feature package (e.g. `analyze`)
+- **Confirm target directory** — default: current workspace root
+
+---
+
+### Phase 2: Create root files
+
+**`go.mod`** (replace `[module]`, `[go-version]`):
+
+```
+module [module]
+
+go [go-version]
+
+require (
+	github.com/sirupsen/logrus v1.9.3
+	github.com/stretchr/testify v1.9.0
+)
+```
+
+**`main.go`** (replace `[module]`, `[subcommand]`, `[feature]`):
+
+```go
+package main
+
+import (
+	"fmt"
+	"os"
+
+	cli[Feature] "[module]/cli/[feature]"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Println("Usage: [binary] [[feature]]")
+		os.Exit(1)
+	}
+
+	switch os.Args[1] {
+	case "[subcommand]":
+		cli[Feature].Run(os.Args)
+	default:
+		fmt.Printf("Unknown command: %s\n", os.Args[1])
+		fmt.Println("Usage: [binary] [[feature]]")
+		os.Exit(1)
+	}
+}
+```
+
+**`Makefile`** (replace `[binary]`):
+
+```makefile
+SHELL := /bin/bash
+
+BINARY := [binary]
+
+all: build lint test
+
+build: install
+	@mkdir -p dist
+	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"
+
+build-arch-os-darwin-amd64:
+	$(MAKE) build-arch-os OS=darwin ARCH=amd64
+
+build-arch-os-darwin-arm64:
+	$(MAKE) build-arch-os OS=darwin ARCH=arm64
+
+build-arch-os-linux-amd64:
+	$(MAKE) build-arch-os OS=linux ARCH=amd64
+
+build-arch-os-linux-arm64:
+	$(MAKE) build-arch-os OS=linux ARCH=arm64
+
+build-arch-os-windows-amd64:
+	$(MAKE) build-arch-os OS=windows ARCH=amd64
+
+build-arch-os:
+	@if [ "${OS}" == "" ]; then echo "ENV OS is required"; exit 1; fi
+	@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) .
+	@echo "Done"
+
+install:
+	go mod download
+
+lint:
+	golangci-lint run ./...
+
+lint-fix:
+	golangci-lint run --fix ./...
+
+test:
+	go test -cover ./...
+
+test-coverage:
+	go test -coverprofile=coverage.out ./...
+	go tool cover -func coverage.out
+
+benchmark:
+	go test -bench . -benchmem -count 5 ./...
+
+clean:
+	rm -rf dist
+	rm -f coverage.out
+
+start:
+	go run ./ [subcommand]
+```
+
+**`.golangci.yml`**:
+
+```yaml
+linters:
+  enable:
+    - errcheck
+    - govet
+    - staticcheck
+    - unused
+    - gosimple
+    - ineffassign
+    - typecheck
+run:
+  timeout: 5m
+```
+
+**`.gitignore`**:
+
+```
+dist/
+coverage.out
+*.pprof
+.DS_Store
+```
+
+**`README.md`** (replace `[binary]`, `[description]`, `[owner]`, `[repo]`):
+
+```markdown
+# [binary]
+
+[description]
+
+## Usage
+
+    [binary] [subcommand] --help
+
+## 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
+```
+
+---
+
+### Phase 3: Create the feature package
+
+**`[feature]/[feature].go`** (replace `[feature]`, `[Feature]`):
+
+```go
+package [feature]
+
+import "github.com/sirupsen/logrus"
+
+// Options holds the parameters for [Feature] analysis.
+type Options struct {
+	Verbose bool
+}
+
+// Result holds the output of a [Feature] run.
+type Result struct {
+	Summary string
+}
+
+// Run executes the [Feature] logic with the given options.
+func Run(opts Options) (Result, error) {
+	if opts.Verbose {
+		logrus.SetLevel(logrus.DebugLevel)
+	}
+	logrus.Debug("[Feature] started")
+
+	// TODO: implement business logic here
+
+	return Result{Summary: "ok"}, nil
+}
+```
+
+**`[feature]/[feature]_test.go`** (replace `[feature]`, `[Feature]`):
+
+```go
+package [feature]
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test[Feature]Run(t *testing.T) {
+	result, err := Run(Options{Verbose: false})
+	require.NoError(t, err)
+	assert.Equal(t, "ok", result.Summary)
+}
+```
+
+---
+
+### Phase 4: Create the CLI package
+
+**`cli/[feature]/[feature].go`** (replace `[module]`, `[feature]`, `[Feature]`, `[subcommand]`):
+
+```go
+package cli[Feature]
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/sirupsen/logrus"
+	"[module]/[feature]"
+)
+
+// Run parses CLI flags for the [subcommand] command and calls the domain package.
+func Run(args []string) {
+	fs := flag.NewFlagSet("[subcommand]", flag.ExitOnError)
+	verbose := fs.Bool("verbose", false, "Show verbose logs during processing")
+
+	if err := fs.Parse(args[2:]); err != nil {
+		fmt.Fprintf(os.Stderr, "error parsing flags: %v\n", err)
+		os.Exit(1)
+	}
+
+	if *verbose {
+		logrus.SetLevel(logrus.DebugLevel)
+	}
+
+	result, err := [feature].Run([feature].Options{
+		Verbose: *verbose,
+	})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println(result.Summary)
+}
+```
+
+---
+
+### Phase 5: Verify and run
+
+After creating all files, run the following in the project root:
+
+```bash
+go mod tidy
+make all
+```
+
+Fix any compile or lint errors before finishing.
+
+---
+
+## Conventions and reminders
+
+- `main.go` dispatches only — no logic.
+- 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).
+- 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.
+- Do not create an `internal/` package unless explicitly justified (importability is preferred).

package/.xdrs/agentme/edrs/devops/005-monorepo-structure.md

@@ -0,0 +1,104 @@
+# agentme-edr-005: Monorepo structure
+
+## Context and Problem Statement
+
+Without a defined monorepo layout, teams independently organize projects in ways that are inconsistent, hard to navigate, and difficult to build uniformly. Shared code gets duplicated, tooling varies per project, and onboarding new contributors is slow because there is no standard entry point or build convention.
+
+What monorepo structure, naming conventions, tooling, and build standards should be followed to keep multiple projects cohesive, discoverable, and easy to build?
+
+## Decision Outcome
+
+**Adopt a standardized monorepo layout with 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.**
+
+For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/002-monorepo-setup/SKILL.md).
+
+### Policies
+
+#### 1. Top-level directory layout
+
+```
+/
+├── shared/               # Resources shared across ALL applications
+│   ├── libs/             # Reusable libraries consumed by applications
+│   └── scripts/          # Build/CI/dev scripts used across applications
+│
+├── <application>/        # One folder per application or project
+│   ├── README.md         # REQUIRED
+│   ├── <module>/         # One folder per compilable module
+│   └── shared/           # Resources shared by modules within THIS application
+│
+├── Makefile              # Root Makefile coordinating all areas
+├── README.md             # REQUIRED — onboarding and quickstart guide
+└── .mise.toml            # Mise tool version configuration
+```
+
+#### 2. Application folders
+
+- Represent a cohesive unit with its own lifecycle (e.g., `mymobileapp`, `graph-visualizer`).
+- **MUST** depend only on resources in `/shared/`. Direct cross-application dependencies are forbidden; use published artifacts (container images, published libraries) instead.
+- **MUST** contain a `README.md` with: purpose, architecture overview, how to build, and how to run.
+
+*Why:* Isolating applications prevents implicit coupling and makes the `shared/` boundary explicit and intentional.
+
+#### 3. Module folders
+
+- A module is a subfolder inside an application that is independently compilable and produces a build artifact.
+- May depend on sibling modules within the same application or on `/shared/` resources.
+- **MUST NOT** depend on modules from other applications.
+
+#### 4. Naming conventions
+
+- All folder and file names **MUST** be **lowercase**.
+- Use hyphens (`-`) to separate words (e.g., `data-loader`, `graph-visualizer`).
+- Avoid abbreviations unless universally understood in the domain (e.g., `cli`, `api`).
+
+#### 5. Makefiles at every level
+
+A `Makefile` **MUST** be present at the repository root, in every application folder, and in every module folder.
+
+Each Makefile **MUST** define at minimum: `build`, `lint`, and `test` targets.
+
+The root `Makefile` **MUST** also define a `setup` target that guides a new contributor to prepare their machine.
+
+*Why:* Makefiles provide a universal, stack-agnostic entry point regardless of programming language.
+
+#### 6. Mise for tooling management
+
+- [Mise](https://mise.jdx.dev/) **MUST** be used to pin all tool versions (compilers, runtimes, CLI tools).
+- A `.mise.toml` **MUST** exist at the repository root.
+- Every language runtime or CLI referenced by any module `Makefile`, CI workflow, or README command **MUST** be pinned in `.mise.toml`.
+- Contributors run `mise install` once after cloning.
+- Agents and contributors **MUST** check `.mise.toml` before using a system-installed compiler, runtime, or CLI.
+- When `.mise.toml` exists, all build, test, lint, and code-generation commands **MUST** run inside the Mise-managed environment, preferably via `mise exec -- <command>` or an activated Mise shell.
+- If a required tool is missing, the first remediation step **MUST** be to update `.mise.toml` or run `mise install`, not to install ad-hoc global tools with language-specific installers such as `go install`, `npm install -g`, `pip install --user`, or `cargo install`.
+- Root and module `Makefile` targets **SHOULD** work correctly when invoked through `mise exec -- make <target>`.
+
+*Why:* Eliminates "works on my machine" build failures by ensuring identical tool versions across all environments.
+
+#### 7. Root README
+
+The root `README.md` **MUST** include: overview, machine setup, quickstart, and a repository map.
+
+#### 8. Git tagging and artifact versioning
+
+All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g., `graphvisualizer/renderer/1.0.0`, `shared/libs/mylib/2.1.0`).
+
+`<module-name>` is preferably the path-like identifier of the module being released. A custom name is allowed but the folder name is strongly preferred.
+
+*Why:* Namespacing tags by module prevents collisions and makes it easy to filter release history when multiple modules release independently.
+
+---
+
+#### 11. Summary of requirements
+
+| Requirement | Scope | Mandatory |
+|---|---|---|
+| Lowercase folder/file names | All | Yes |
+| `README.md` per application | Application folders | Yes |
+| `Makefile` with `build`, `lint`, `test` | All modules and applications | Yes |
+| Root `Makefile` with `setup` target | Repository root | Yes |
+| Root `README.md` with setup + quickstart | Repository root | Yes |
+| Mise `.mise.toml` at root | Repository root | Yes |
+| Applications depend only on `/shared/` | Application folders | Yes |
+| Modules depend only on siblings or `/shared/` | Module folders | Yes |
+| Git tags follow `<module-name>/<semver>` format | All modules | Yes |

package/.xdrs/agentme/edrs/devops/006-github-pipelines.md

@@ -0,0 +1,170 @@
+# agentme-edr-006: GitHub CI/CD pipelines
+
+## Context and Problem Statement
+
+Without a defined GitHub Actions pipeline structure, projects end up with inconsistent workflows — some combine CI and publishing in a single file, others trigger builds on wrong events, and release tagging is done ad-hoc. This leads to accidental publishes, broken release histories, and non-reproducible builds.
+
+What GitHub Actions workflows should every project follow to ensure a safe, predictable, and automated CI/CD lifecycle?
+
+## Decision Outcome
+
+**Use three separate, purpose-scoped GitHub Actions workflows: `ci.yml` for build verification on PRs and main, `release.yml` for calculating and creating a version tag with monotag, and `publish.yml` for publishing artifacts when a version tag is pushed.**
+
+Separating these concerns eliminates accidental publishes from CI runs, ensures monotag has access to the full git history, and makes each workflow independently auditable and re-runnable.
+
+### Implementation Details
+
+#### Workflow overview
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | `pull_request` → `main`, `push` → `main` | Build, lint, and test the codebase |
+| `release.yml` | `workflow_dispatch` | Tag the next version using monotag |
+| `publish.yml` | `push` of tags matching `*` | Publish artifacts for the tagged version |
+
+All workflows run on `ubuntu-latest`. Tool versions MUST be managed by Mise via `jdx/mise-action`. Projects should have a .mise.toml file to configure it
+
+---
+
+#### 1. CI workflow — `.github/workflows/ci.yml`
+
+Triggered on every PR targeting `main` and every push to `main`. Runs the standard `build`, `lint`, and `test` targets from the root Makefile and fails the workflow if any step exits non-zero.
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jdx/mise-action@v3
+      - run: make build
+      - run: make lint
+      - run: make test
+```
+
+*Why separate steps:* Separate steps surface exactly which phase failed (build, lint, or test) without requiring log inspection.
+
+---
+
+#### 2. Release workflow — `.github/workflows/release.yml`
+
+Manually dispatched (`workflow_dispatch`). Calculates the next semantic version tag using **monotag** and pushes that tag to the repository. Pushing the tag then automatically triggers the publish workflow.
+
+The checkout step **must** use `fetch-depth: 0` so monotag can traverse the full commit history to determine the correct next version.
+
+```yaml
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: 'Pre-release'
+        type: boolean
+        default: true
+
+jobs:
+  create-tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          # this is needed if you want the tag push to trigger another workflow
+          # create a personal token and set a secret with name GH_PERSONAL_TOKEN
+          # https://github.com/orgs/community/discussions/27028
+          token: ${{ secrets.GH_PERSONAL_TOKEN }}
+      - name: Create tag and push to repo
+        run: |
+          git config --global user.email "noreply@github.com"
+          git config --global user.name "Github Wokflow"
+          npx -y monotag@latest tag-push ${{ inputs.prerelease == true && '--pre-release' || '' }}
+```
+
+*Why `workflow_dispatch`:* Manual triggering gives developers explicit control over when a new release tag is created, preventing unintended releases from routine merges.
+
+*Why `contents: write`:* Required to allow the workflow to push the new tag back to the repository.
+
+---
+
+#### 3. Publish workflow — `.github/workflows/publish.yml`
+
+Triggered exclusively when a tag matching `v*.*.*` is pushed to the repository. This ensures only explicitly tagged commits produce published artifacts. Runs `make publish` against the tagged commit.
+
+```yaml
+name: publish
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jdx/mise-action@v3
+      - run: make build
+      - run: make lint
+      - run: make test
+      - run: git reset --hard HEAD
+      - run: make publish
+
+```
+
+*Why rebuild on publish:* The checkout is done from the exact tag commit. Rebuilding ensures the published artifact matches exactly what is tagged, rather than relying on a prior CI artifact.
+
+*Why `id-token: write`:* Required for npm provenance attestation via `npm publish --provenance`, as specified in [agentme-edr-003](003-javascript-project-tooling.md).
+
+---
+
+#### Required secrets and permissions
+
+| Secret / Permission | Used in | Purpose |
+|--------------------|---------|---------| 
+| `GITHUB_TOKEN` (built-in) | `release.yml` | Push newly calculated tag back to the repository |
+| `id-token: write` | `publish.yml` | Generate OIDC token for npm provenance |
+| `contents: write` | `release.yml` | Allow the workflow job to push tags |
+
+---
+
+#### Relationship between workflows
+
+```
+PR opened / push to main
+        │
+        ▼
+  ci.yml runs
+  (build + lint + test)
+        │
+        ▼ (merge to main)
+  developer dispatches
+  release.yml manually
+        │
+        ▼
+  monotag calculates
+  next semver tag
+        │
+        ▼
+  tag pushed → v1.2.3
+        │
+        ▼
+  publish.yml triggered
+  (build + publish artifacts)
+```
+