agentme 0.10.0 → 0.12.0

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

@@ -19,7 +19,7 @@ Every project must meet six minimum quality standards: a Getting Started section
 
 These standards form a non-negotiable baseline. Individual projects may raise the bar but must never fall below it.
 
-### Implementation Details
+### Details
 
 #### 01-readme-must-have-getting-started
 
@@ -31,7 +31,7 @@ These standards form a non-negotiable baseline. Individual projects may raise th
 
 **Required README structure:**
 
-```markdown
+````markdown
 # Project Name
 
 One-line description.
@@ -46,7 +46,7 @@ npm install my-package
 import { myFunction } from "my-package";
 myFunction({ input: "value" });
 ```
-```
+````
 
 ---
 

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

@@ -17,7 +17,7 @@ What error handling practices should be followed across all languages and projec
 
 **Follow a set of consistent error handling practices: catch only where you can handle, return errors as values at interfaces, centralize repetitive catch logic, communicate failure clearly at process and service boundaries, and exercise error paths with dedicated tests.**
 
-### Implementation Details
+### Details
 
 #### 01-catch-only-where-handled
 

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

@@ -19,7 +19,7 @@ Question: What policy should developers follow to continuously enrich XDRs so re
 
 Developers must treat reusable missing guidance discovered during implementation as an XDR gap to be proposed and reviewed, not as permanent prompt-only context or repeated vibe coding.
 
-### Implementation Details
+### Details
 
 - The main objective is sharing, discussing, and converging practices across teams. Controlled divergence during exploration is acceptable, but recurring successful decisions must be converged into shared XDRs.
 - The non _local scope exists to share practices across projects, company areas, and functionally organized teams. Decisions placed in `_local` should be truly specific to the needs of a single application or repository.
@@ -43,4 +43,4 @@ Developers must treat reusable missing guidance discovered during implementation
 - [_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-policy skill](../../../../.github/skills/002-write-policy/SKILL.md)
+- [002-write-policy skill](../../../_core/adrs/principles/skills/002-write-policy/SKILL.md)

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

@@ -19,7 +19,7 @@ What baseline structure rules must every buildable module follow regardless of l
 
 Language-specific EDRs may add ecosystem details, but they must not redefine these baseline folder responsibilities.
 
-### Implementation Details
+### Details
 
 #### 01-module-must-own-folder-root
 

package/.xdrs/agentme/edrs/principles/022-secrets-management.md

@@ -0,0 +1,128 @@
+---
+name: agentme-edr-policy-022-secrets-management
+description: Defines how secrets (API keys, passwords, tokens, credentials, private certificates) must be stored, fetched, and provisioned. Use when implementing secret handling in any language or deployment target.
+apply-to: All software projects handling secrets
+valid-from: 2026-05-28
+---
+
+# agentme-edr-policy-022: Secrets management
+
+## Context and Problem Statement
+
+A "secret" is any sensitive information whose exposure would compromise security or access control. Examples include API keys, passwords, authentication tokens, credentials, and private certificates. Plain configuration data (feature flags, endpoint URLs, port numbers) is not a secret.
+
+Secrets stored on disk — even in `.env` files excluded from version control — are vulnerable to accidental exposure, tooling leaks, and lateral movement after a compromise. Hardcoded or cached secrets resist rotation and create synchronization headaches across environments.
+
+What practices should projects follow to handle secrets securely across local development and cloud deployments?
+
+## Decision Outcome
+
+**Use native OS keychains for local development and cloud secret managers for deployed environments, accessed through a unified connector with ordered fallback.**
+
+All implementation practices derive from three guiding principles:
+
+1. **Least exposure** — minimize the means, timespan, and surface of contact with the secret.
+2. **Easiness in secret rotation** — design so rotating a secret requires no code change or redeployment.
+3. **Support for local and cloud deployment runs** — the same application code must work transparently in both environments.
+
+### Details
+
+#### 01-no-secrets-on-disk
+
+Secrets must never be stored on the disk of a developer machine or server. This includes `.env` files (even when gitignored), plaintext config files, embedded in source code, or any other file-based storage.
+
+The only acceptable local persistence is through the operating system's native secret manager (e.g., macOS Keychain, Windows Credential Manager, Linux Secret Service).
+
+---
+
+#### 02-local-dev-uses-native-keychain
+
+During local development, secrets must be stored and retrieved using the native OS secret manager. Use cross-platform libraries to keep the code OS-agnostic:
+
+| Language | Library |
+|----------|---------|
+| Python | `keyring` |
+| JavaScript/TypeScript | `cross-keychain` |
+| Go | `go-keyring` |
+
+The "group" (service name) defaults to the module name. The secret identifier should match the ID used in the cloud secret manager for consistency.
+
+---
+
+#### 03-fallback-lookup-order
+
+Secret fetching must implement a fallback chain in the following order:
+
+1. **Native OS keychain** — attempt to retrieve the secret using the local keychain library (used during local development).
+2. **Cloud secret manager** — if not found locally, fetch from the configured cloud secret manager (AWS Secrets Manager, Azure Key Vault, etc.) (used in cloud environments).
+3. **Raise an exception** — if both lookups fail, raise an exception with a clear message indicating both failed paths.
+
+Example error message:
+```
+Secret 'db-password' could not be found in keychain under group 'mymodule' or in AWS Secrets Manager under secretId 'db-password'
+```
+
+---
+
+#### 04-secret-fetching-in-connector
+
+The secret fetching logic (including the fallback chain from rule 03) must live in a dedicated "connector" module or function. This isolates secret-access concerns from business logic and provides a single point to configure secret sources, caching policy, and error handling.
+
+---
+
+#### 05-setup-secrets-makefile-target
+
+Every module that requires secrets must expose a `setup-secrets` Makefile target. This target:
+
+- Prompts the user for each required secret value interactively.
+- If the user provides an empty value, the existing secret is not updated.
+- Stores the provided value in the native OS keychain.
+- Uses the module name as the default group (service name).
+- Uses secret identifiers that match the cloud secret manager IDs.
+
+The desired developer flow:
+
+```text
+$ make run
+Error: Secret 'api-key' could not be found in keychain under group 'mymodule'
+       or in AWS Secrets Manager under secretId 'api-key'
+
+$ make setup-secrets
+Enter value for 'api-key' (leave empty to skip):
+> ****
+Secret 'api-key' stored in keychain under group 'mymodule'.
+
+$ make run
+# Application starts successfully
+```
+
+---
+
+#### 06-never-log-or-leak-secrets
+
+Secrets must never be logged under any circumstance or sent to any service that is not clearly the intended consumer of that secret (authentication, encryption, etc.). This applies to all log levels including debug and trace. Error messages must reference the secret name or identifier, never its value.
+
+---
+
+#### 07-prefer-dynamic-fetching
+
+Wherever possible, fetch secrets dynamically from the secret manager at the time of use. Avoid storing secrets in global variables or caching them indefinitely. Dynamic fetching through a specialized service enables:
+
+- Automatic password rotation without redeployment.
+- Immediate propagation of rotated secrets.
+- Reduced window of exposure if memory is compromised.
+
+Short-lived caching (e.g., a few minutes) is acceptable when performance requires it, but must have an explicit TTL.
+
+---
+
+#### 08-prefer-fetching-at-point-of-use
+
+Prefer fetching the secret inside the function that directly needs it rather than passing it through multiple layers as a function argument. This minimizes the exposure surface by reducing the number of code paths that handle the raw secret value.
+
+Passing secrets via function arguments is acceptable when the consuming function cannot access the connector directly, but the default design should fetch at the point of use.
+
+## References
+
+- [agentme-edr-008](../devops/008-common-targets.md) - Common development script names (defines Makefile target conventions)
+- [agentme-edr-009](009-error-handling.md) - Error handling (governs how the fallback exception should be raised)

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

@@ -2,13 +2,13 @@
 
 ## Overview
 
-This article explains how architects, engineers and business professionals should recognize, organize, and promote reusable delivery decisions into XDRs as a continuous improvement activity. It is aimed at people working with coding agents, vibe-coding loops, or SDD-oriented delivery who need a practical path from task friction to shared documentation.
+A practical guide for recognizing recurring delivery decisions and promoting them into shared XDRs. Intended for engineers, architects, and business professionals working with coding agents or SDD-oriented delivery.
 
-Continuous improvement matters because delivery decisions do not stay correct forever. Team structures change, platforms evolve, tools mature, and the trade-offs behind earlier choices shift over time. If XDRs are not revisited and improved continuously, previously useful decisions become stale guidance and eventually turn into a form of legacy documentation that misleads delivery instead of guiding it.
+## Content
 
-Continuous improvement also keeps the target state explicit. As XDRs evolve across projects and tracks, teams need a clear shared view of where they are trying to converge, what remains intentionally different, and what should be treated as technical debt on the path toward that target. Keeping XDRs current reduces confusion about the desired future state and helps each project evolve toward it deliberately instead of drifting through ad hoc local decisions.
+Delivery decisions do not stay correct forever. Team structures change, platforms evolve, tools mature, and the trade-offs behind earlier choices shift over time. If XDRs are not revisited and improved continuously, previously useful decisions become stale guidance that misleads delivery instead of guiding it.
 
-## Content
+Keeping XDRs current also makes the target state explicit. Teams need a clear shared view of where they are converging, what remains intentionally different, and what is technical debt on the path to that target.
 
 ### Start from delivery friction
 
@@ -90,4 +90,4 @@ If the same clarification would likely be needed in another feature, by another
 - [_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-policy skill](../../../../../.github/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs
+- [002-write-policy skill](../../../../_core/adrs/principles/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.34.1"
@@ -22,6 +22,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.28.0"
+    "xdrs-core": "^0.28.1"
   }
 }