agentme 0.3.3 → 0.6.0

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

@@ -13,12 +13,12 @@ metadata:
 
 ## Overview
 
-Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../../.xdrs/agentme/edrs/devops/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.
+Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../005-monorepo-structure.md):
+top-level application folders, independent module roots, sibling example and multi-module test
+areas, 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 EDRs: [agentme-edr-005](../../../.xdrs/agentme/edrs/devops/005-monorepo-structure.md), [agentme-edr-013](../../../.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md)
+Related EDRs: [agentme-edr-005](../../005-monorepo-structure.md), [agentme-edr-013](../../../governance/013-contributing-guide-requirements.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -51,10 +51,12 @@ golangci-lint = "1.57"
 Coordinates `build`, `lint`, and `test` across all applications. Also exposes a `setup` target.
 
 ```makefile
-.PHONY: build lint test setup
+.PHONY: all build lint test clean setup
 
 APPS := <app1> <app2>   # replace with actual application names
 
+all: build lint test
+
 build:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) build &&) true
 
@@ -64,12 +66,25 @@ lint:
 test:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) test &&) true
 
+clean:
+   $(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
+   rm -rf .cache
+
 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 `.gitignore`
+
+Must ignore shared artifact and cache folders:
+
+```gitignore
+dist/
+.cache/
+```
+
 #### Root `README.md`
 
 Must include four sections:
@@ -162,10 +177,12 @@ For each application:
 3. **Create `<app>/Makefile`** that delegates to each module:
 
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
 
    MODULES := <module1> <module2>   # replace with actual module names
 
+   all: build lint test
+
    build:
    	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) build &&) true
 
@@ -174,10 +191,16 @@ For each application:
 
    test:
    	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) test &&) true
+
+   clean:
+   	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) clean &&) true
+   	rm -rf .cache
    ```
 
 4. **Create `<app>/shared/`** — leave empty if no cross-module shared code exists yet.
 
+5. **Create sibling aggregation folders when needed**: `<app>/examples/`, `<app>/tests_integration/`, and `<app>/tests_benchmark/` for artifacts that apply to multiple modules.
+
 ---
 
 ### Phase 5: Scaffold each module
@@ -186,11 +209,15 @@ 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:
+2. **Create `<app>/<module>/README.md`** with consumer usage first and short developer commands at the end.
+
+3. **Create `<app>/<module>/Makefile`** with the common targets, adapted to the module's language. Redirect persistent caches into `.cache/` and write distributable artifacts to `dist/`.
 
    **Go:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	go build ./...
@@ -200,11 +227,16 @@ For each module inside an application:
 
    test:
    	go test ./... -cover
+
+   clean:
+	rm -rf dist .cache
    ```
 
    **Node.js / TypeScript:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	npm run build
@@ -214,11 +246,16 @@ For each module inside an application:
 
    test:
    	npm test
+
+   clean:
+	rm -rf dist .cache
    ```
 
    **Python:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	pip install -e .
@@ -228,9 +265,14 @@ For each module inside an application:
 
    test:
    	pytest
+
+   clean:
+	rm -rf dist .cache
    ```
 
-3. **Add source files** appropriate to the language, placing them inside the module folder.
+4. **Add source files** appropriate to the language, placing them inside the module folder.
+
+5. **Place module-specific integration tests and benchmarks predictably**: `<module>/tests_integration/` and `<module>/tests_benchmark/` when they are not co-located by language convention.
 
 ---
 
@@ -242,8 +284,10 @@ After scaffolding, run the following checks and fix any issues:
 - `make lint` at the repository root passes.
 - `make test` at the repository root passes.
 - All folder and file names are lowercase and use hyphens.
+- The root `.gitignore` ignores `dist/` and `.cache/`.
 - A `CONTRIBUTING.md` exists at the repository root and covers bugs, feature discussions, pull requests, Conventional Comments, and small focused changes.
 - Every application folder has a `README.md` covering all four required sections.
+- Every module folder has a `README.md`, `Makefile`, `dist/` location, and `.cache/` strategy.
 - A `.mise.toml` exists at the repository root with all required tool versions pinned.
 
 ---
@@ -256,8 +300,10 @@ After scaffolding, run the following checks and fix any issues:
 pcb-devices/
 ├── README.md
 ├── Makefile
+├── examples/
 ├── shared/
 └── firmware/
+   ├── README.md
     └── Makefile
 ```
 

package/.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-013-contributing-guide-requirements
+description: Defines the minimum contributor workflow guidance required in root CONTRIBUTING.md files. Use when scaffolding or reviewing contribution processes.
+---
+
 # agentme-edr-013: Contributing guide requirements
 
 ## Context and Problem Statement

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

@@ -13,6 +13,7 @@ Foundational standards, principles, and guidelines.
 - [agentme-edr-007](principles/007-project-quality-standards.md) - **Project quality standards**
 - [agentme-edr-009](principles/009-error-handling.md) - **Error handling**
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy**
+- [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure**
 
 ## Articles
 
@@ -26,6 +27,8 @@ 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))*
+- [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
+- [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards**
 - [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ## Devops

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

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-011-service-health-check-endpoint
+description: Defines the required health endpoint contract for service availability and dependency readiness checks. Use when implementing or reviewing service health endpoints.
+---
+
 # agentme-edr-011: Service health check endpoint
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/002-coding-best-practices.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-002-coding-best-practices
+description: Defines cross-language coding practices for keeping code readable, modular, and synchronized with tests and documentation. Apply across projects adopting agentme engineering standards.
+---
+
 # agentme-edr-002: Coding best practices
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/004-unit-test-requirements.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-004-unit-test-requirements
+description: Defines unit test requirements for assertions, offline execution, coverage, shared setup, and real-code preference. Use when writing or reviewing tests.
+---
+
 # agentme-edr-004: Unit test requirements
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/007-project-quality-standards.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-007-project-quality-standards
+description: Defines minimum project quality standards for README onboarding, testing, linting, XDR compliance, and runnable examples. Use when scaffolding or reviewing projects.
+---
+
 # agentme-edr-007: Project quality standards
 
 ## Context and Problem Statement
@@ -60,7 +65,7 @@ A unit test suite must run automatically before every release. Failing tests mus
 
 ### 3. The project MUST comply with all applicable workspace XDRs
 
-All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
+All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
 
 **Requirements:**
 - Review applicable XDRs before any significant implementation
@@ -80,7 +85,7 @@ Projects larger than 10 files or 200 lines of code must have a linter configured
 
 **Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
 
-**Reference:** [agentme-edr-003](003-javascript-project-tooling.md) for JavaScript-specific tooling.
+**Reference:** [agentme-edr-003](../application/003-javascript-project-tooling.md) for JavaScript-specific tooling.
 
 ---
 

package/.xdrs/agentme/edrs/principles/009-error-handling.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-009-error-handling
+description: Defines error handling practices for catching, propagating, surfacing, and testing failures consistently across projects. Use when implementing interfaces and failure paths.
+---
+
 # agentme-edr-009: Error handling
 
 ## Context and Problem Statement

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-012-continuous-xdr-improvement-policy
+description: Defines how teams should promote reusable implementation guidance into shared XDRs instead of keeping it in prompts or local habits. Use when recurring decisions surface during delivery.
+---
+
 # agentme-edr-012: Continuous xdr improvement policy
 
 ## Context and Problem Statement
@@ -33,7 +38,7 @@ Developers must treat reusable missing guidance discovered during implementation
 
 ## References
 
-- [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md)
+- [_core-adr-001](../../../_core/adrs/principles/001-xdrs-core.md)
 - [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md)
 - [agentme-article-001](articles/001-continuous-xdr-improvement.md)
 - [002-write-xdr skill](../../../../.github/skills/002-write-xdr/SKILL.md)

package/.xdrs/agentme/edrs/principles/016-cross-language-module-structure.md

@@ -0,0 +1,133 @@
+---
+name: agentme-edr-016-cross-language-module-structure
+description: Defines the baseline module-root structure, artifact locations, cache placement, README expectations, examples layout, and test folder conventions across languages. Use when creating or reviewing buildable modules.
+---
+
+# agentme-edr-016: Cross-language module structure
+
+## Context and Problem Statement
+
+The language-specific tooling EDRs currently describe similar module layouts in different ways, which causes drift in example placement, cache folders, README expectations, and test organization.
+
+What baseline structure rules must every buildable module follow regardless of language?
+
+## Decision Outcome
+
+**Standardize every buildable module around its own folder root, with `dist/`, `.cache/`, sibling consumer examples, a module README, and predictable test locations.**
+
+Language-specific EDRs may add ecosystem details, but they must not redefine these baseline folder responsibilities.
+
+### Implementation Details
+
+#### 1. Every buildable or publishable module MUST own its folder root
+
+A module is the smallest independently buildable, testable, or publishable unit. It MUST live in its own folder and that folder MUST contain:
+
+- a `Makefile` following [agentme-edr-008](../devops/008-common-targets.md)
+- a `README.md` for the module itself
+- all configuration files required to build, lint, test, package, or publish that module
+- its generated `dist/` directory when the module produces distributable artifacts
+- a module-local `.cache/` when tool caches are not intentionally shared with a parent aggregation root
+
+Example module root:
+
+```text
+<module>/
+├── Makefile
+├── README.md
+├── dist/
+├── .cache/
+└── ... language-specific sources and config ...
+```
+
+#### 2. Parent folders are aggregation roots, not hidden implementation buckets
+
+Parent folders such as a repository root, an application folder, or `lib/` may aggregate multiple modules. They may also hold shared consumer examples or multi-module test harnesses.
+
+They MUST keep the public aggregation obvious: deleting an aggregation folder should remove a coherent API surface or entry-point area, not scatter unrelated internal implementation across the repository.
+
+Recommended aggregation pattern:
+
+```text
+<parent>/
+├── <module-a>/
+├── <module-b>/
+├── examples/
+├── tests_integration/
+└── tests_benchmark/
+```
+
+#### 3. Build and publish outputs MUST go to `dist/`
+
+Distributable outputs such as packages, wheels, archives, generated binaries, or packed example inputs MUST be written under the module's `dist/` folder.
+
+`dist/` MUST be gitignored.
+
+#### 4. Persistent tool caches MUST live under `.cache/`
+
+Tool-generated caches and disposable machine-local state MUST be redirected into the nearest intended `.cache/` folder, either at monorepo level or module level.
+
+Examples include:
+
+- linter caches
+- test runner caches
+- transpiler incremental state
+- formatter caches
+- dependency-manager caches when local caching is desired
+
+If a tool cannot natively choose its cache path, the module `Makefile` MUST wrap or clean that tool so persistent cache files do not remain scattered outside `.cache/` after standard targets run.
+
+`.cache/` MUST be gitignored.
+
+#### 5. Consumer examples MUST sit outside the module they exercise
+
+Examples that demonstrate how to consume a library or reusable module MUST live in a sibling `examples/` folder under the nearest aggregation root, not inside the module folder itself.
+
+Examples MUST exercise the module through its public distribution surface:
+
+- use the package built into `dist/` when the ecosystem supports local packaged artifacts
+- otherwise use the public module path or equivalent consumer-facing import surface, never relative source-file imports or direct references to internal implementation paths
+
+Example:
+
+```text
+lib/
+└── mymodule/
+
+examples/
+└── using-mymodule/
+```
+
+#### 6. Every module README MUST explain both usage and development
+
+Each module MUST contain a `README.md` that shows how to use the module as a consumer.
+
+The end of the README MUST also include short developer instructions for that module, covering at least the standard build, lint, and test entry points.
+
+Repository-level READMEs may describe the workspace, but they do not replace the module README.
+
+#### 7. Unit, integration, and benchmark tests use predictable locations
+
+Unit tests SHOULD be co-located with the file they exercise when that is idiomatic and common for the language.
+
+When co-location is uncommon or awkward for the ecosystem, unit tests SHOULD live under `<module>/tests/`.
+
+Integration tests MUST live in one of these locations:
+
+- `<module>/tests_integration/` when they cover one module
+- `<parent>/tests_integration/` when they cover multiple sibling modules
+
+Benchmark tests MUST live in one of these locations:
+
+- co-located with the source when the language has a first-class benchmark convention there
+- `<module>/tests_benchmark/` for module-specific harnesses or datasets
+- `<parent>/tests_benchmark/` when they cover multiple sibling modules
+
+#### 8. Module Makefiles MUST expose the shared target vocabulary
+
+Every module `Makefile` MUST expose the common target names from [agentme-edr-008](../devops/008-common-targets.md). At minimum, modules MUST provide `build`, `lint`, and `test`, and SHOULD also provide `all`, `clean`, and `lint-fix` when meaningful.
+
+## References
+
+- [agentme-edr-005](../devops/005-monorepo-structure.md) - Monorepo aggregation and delegation rules
+- [agentme-edr-008](../devops/008-common-targets.md) - Shared Makefile target names

package/.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md

@@ -51,7 +51,7 @@ Good opening questions:
 
 ### How should you organize the XDR?
 
-Follow the XDR template from [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md). Keep the document small, explicit, and decision-focused.
+Follow the XDR template from [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md). Keep the document small, explicit, and decision-focused.
 
 Use this checklist:
 
@@ -87,7 +87,7 @@ If the same clarification would likely be needed in another feature, by another
 
 ## References
 
-- [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.md) - XDR structure, numbering, and mandatory template
-- [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
+- [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md) - XDR structure, numbering, and mandatory template
+- [_core-article-001](../../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
 - [agentme-edr-012](../012-continuous-xdr-enrichment.md) - Shared-first XDR enrichment policy and 80% coverage target
 - [002-write-xdr skill](../../../../../.github/skills/002-write-xdr/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.3.3",
+  "version": "0.6.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",
-    "xdrs-core": "^0.14.5"
+    "xdrs-core": "^0.16.0"
   },
   "bin": "bin/filedist.js",
   "files": [
@@ -90,11 +90,30 @@
             ".github/agents/speckit*",
             ".github/prompts/speckit*",
             ".specify/**"
+          ],
+          "exclude": [
+            ".specify/templates/**"
           ]
         },
         "output": {
           "path": ".",
-          "gitignore": false
+          "gitignore": false,
+          "readonly": true
+        },
+        "presets": [
+          "speckit"
+        ]
+      },
+      {
+        "selector": {
+          "files": [
+            ".specify/templates/**"
+          ]
+        },
+        "output": {
+          "path": ".",
+          "gitignore": false,
+          "readonly": false
         },
         "presets": [
           "speckit"
@@ -110,6 +129,7 @@
           "path": ".",
           "managed": false,
           "skipIfExists": true,
+          "readonly": false,
           "gitignore": false
         },
         "presets": [