agentme 0.2.0 → 0.3.1

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](../../005-monorepo-structure.md):
+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.
 
-Related EDR: [agentme-edr-005](../../005-monorepo-structure.md)
+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)
 
 ## Instructions
 
@@ -96,6 +96,29 @@ Must include four sections:
 | `<app2>/`           | <Short description of app2>        |
 ```
 
+#### Root `CONTRIBUTING.md`
+
+Must explain the contribution workflow in a short, explicit way.
+
+```markdown
+# Contributing
+
+## Bugs
+Report bugs in GitHub issues with steps to reproduce, expected behavior, and actual behavior.
+
+## Features
+Discuss feature ideas in an issue before opening a pull request so scope and approach can be agreed first.
+
+## Pull requests
+Submit fixes and features through pull requests from feature branches targeting `main`.
+
+## Review etiquette
+Use [Conventional Comments](https://conventionalcomments.org/) in review feedback.
+
+## Keep changes focused
+Keep pull requests small and focused enough that review and discussion stay efficient.
+```
+
 ---
 
 ### Phase 3: Create the `shared/` area
@@ -219,6 +242,7 @@ 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.
+- 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.
 - A `.mise.toml` exists at the repository root with all required tool versions pinned.
 
@@ -267,4 +291,4 @@ test:
 - **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.
+- **Existing files:** Never overwrite existing `README.md`, `CONTRIBUTING.md`, or `Makefile` files without user confirmation. Diff and propose additions instead.

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

@@ -0,0 +1,37 @@
+# agentme-edr-013: Contributing guide requirements
+
+## Context and Problem Statement
+
+Projects often document contributor expectations inconsistently or only inside README files, PR templates, or tribal knowledge. That causes avoidable review churn, premature feature implementation, and unfocused pull requests.
+
+What contributor workflow guidance must every project publish so contributors know how to report bugs, discuss features, and submit changes?
+
+## Decision Outcome
+
+**Every project must publish a root CONTRIBUTING.md with a small, explicit contribution workflow.**
+
+Projects must keep a `CONTRIBUTING.md` file at the repository root. The file must explain where bugs, feature discussions, and code changes belong so contributors follow a predictable workflow before opening pull requests.
+
+### Implementation Details
+
+- Every project **MUST** have a root `CONTRIBUTING.md`.
+- The guide **MUST** direct bug reports to issues.
+- The guide **MUST** direct feature ideas and feature discussions to issues before implementation starts.
+- The guide **MUST** state that fixes and features are contributed through pull requests.
+- The guide **MUST** state that pull requests come from feature branches targeting `main`.
+- The guide **MUST** ask reviewers and contributors to use [Conventional Comments](https://conventionalcomments.org/) for review feedback.
+- The guide **MUST** ask contributors to keep pull requests small enough to keep review and discussion focused.
+- Project scaffolding skills **SHOULD** create the file by default when they initialize a repository.
+- The content **SHOULD** stay concise and practical; do not turn `CONTRIBUTING.md` into a duplicate of `README.md`.
+
+## Considered Options
+
+* (REJECTED) **Keep contribution rules implicit** - Rely on README text, issue templates, or maintainers explaining the workflow ad hoc.
+  * Reason: Inconsistent contributor behavior and avoidable review overhead.
+* (CHOSEN) **Require a dedicated CONTRIBUTING.md** - Publish a short, explicit contribution workflow in a predictable location.
+  * Reason: Easy to discover, simple to scaffold, and clear enough for both humans and agents.
+
+## References
+
+- [agentme-edr-005 - Monorepo structure](../devops/005-monorepo-structure.md)
+- [002-monorepo-setup skill](../devops/skills/002-monorepo-setup/SKILL.md)

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

@@ -4,12 +4,6 @@ Engineering decisions specific to the agentme project: a curated library of XDRs
 
 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.
@@ -18,6 +12,13 @@ Foundational standards, principles, and guidelines.
 - [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**
+- [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy**
+
+## Articles
+
+Synthetic views combining agentme XDRs and skills around a specific topic.
+
+- [agentme-article-001](principles/articles/001-continuous-xdr-improvement.md) - **Continuous XDR improvement** (what an XDR is, when to write one, how to discuss it, how to organize it, workflow)
 
 ## Application
 
@@ -25,6 +26,7 @@ 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))*
+- [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ## Devops
 
@@ -34,6 +36,12 @@ Repository structure, build conventions, and CI/CD pipelines.
 - [agentme-edr-006](devops/006-github-pipelines.md) - **GitHub CI/CD pipelines**
 - [agentme-edr-008](devops/008-common-targets.md) - **Common development script names**
 
+## Governance
+
+Contribution and collaboration standards shared across projects.
+
+- [agentme-edr-013](governance/013-contributing-guide-requirements.md) - **Contributing guide requirements**
+
 ## Observability
 
 Health, metrics, logging, and monitoring standards.

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

@@ -0,0 +1,39 @@
+# agentme-edr-012: Continuous xdr improvement policy
+
+## Context and Problem Statement
+
+Teams using AI agents, vibe coding, and SDD often keep important implementation guidance only in prompts, review comments, or local habits. This slows delivery, fragments practices across teams, and forces repeated clarification.
+
+Question: What policy should developers follow to continuously enrich XDRs so reusable engineering decisions are shared instead of remaining implicit?
+
+## Decision Outcome
+
+**Develop features with shared-first XDR enrichment and controlled divergence**
+
+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
+
+- 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.
+- When developers or coding agents need too much detailed steering to complete a task, they must reflect on whether those details would help other teams or future implementations. If yes, create or update an XDR proposal in the broadest appropriate shared scope.
+- This includes cases where an agent implemented a feature without a framework, pattern, coding standard, or other practice that should likely be standardized. Missing reusable guardrails should trigger an XDR proposal.
+- Teams should aim to keep at least 80% of big coding decisions covered by accepted XDRs. Big decisions include framework or tool selection, overall code organization, monorepo structure, complex business flows, and coding standards.
+- If a big decision is not yet covered, developers should either propose a new XDR or document why the decision is intentionally local and should not be shared.
+- Leaders responsible for the affected scope are accountable for reviewing XDR proposals, adjusting them, and publishing the accepted decision.
+- It is good practice to ask the coding agent which missing XDRs made the task harder, increased adjustment rounds, or forced more vibe coding. Those gaps should feed the XDR backlog.
+- In SDD, specifications describe the feature being built; XDRs describe reusable decisions and guardrails that should survive beyond one feature. Do not keep durable engineering policy only inside feature specs.
+
+## Considered Options
+
+* (REJECTED) **Force all decisions into local scopes first** - Safer for a single repository but weak for reuse.
+  * Reason: It overuses `_local`, reduces cross-team discussion, and turns shared practices into isolated variants.
+* (CHOSEN) **Promote reusable development guidance into shared XDRs while keeping truly specific decisions local** - Balance exploration with convergence.
+  * Reason: It preserves local autonomy for application-specific needs while making reusable practices discussable, reviewable, and distributable.
+
+## References
+
+- [_core-adr-001](../../../_core/adrs/principles/001-xdr-standards.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/articles/001-continuous-xdr-improvement.md

@@ -0,0 +1,93 @@
+# agentme-article-001: Continuous XDR improvement
+
+## 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.
+
+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.
+
+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.
+
+## Content
+
+### Start from delivery friction
+
+The trigger for a new XDR is usually undocumented work that creates friction. That friction often appears when a feature needs repeated clarification about a business flow, integration pattern, code organization rule, or tool choice before the agent can produce acceptable code.
+
+Common signals:
+
+- The coding agent needs the same steering more than once.
+- Reviews keep repeating the same correction or design preference.
+- A flow depends on rules that are stable beyond one feature.
+- A team solved a delivery problem in a way that other teams could reuse.
+
+### What is an XDR?
+
+An XDR is a short decision record that captures a reusable choice and the reason for it. XDRs can be architectural (ADR), business (BDR), or engineering (EDR). They are the durable source of truth; prompts, review comments, and specs are not.
+
+### Decide whether it should become an XDR
+
+Write or propose an XDR when a task depends on a decision that will likely be reused beyond one feature or repository. Common triggers are repeated prompt explanations, recurring review comments, and cases where an agent needed heavy steering on a framework, coding standard, tool, architecture pattern, or business flow.
+
+Keep genuinely application-specific details in `_local`. Shared XDRs should capture decisions that help more than one team, product area, or recurring workflow.
+
+Before drafting, reduce the issue to one reusable decision:
+
+1. Name the friction clearly.
+2. Identify the decision behind it.
+3. Decide whether it is shared or local.
+4. Choose the right XDR type and subject.
+5. Capture only durable guidance, not ticket-specific detail.
+
+### How do you initiate the discussion?
+
+Start with the decision gap, not the preferred answer. Explain what slowed the work down, what had to be clarified manually, and who else would benefit from the guidance. If useful, ask the coding agent which missing XDRs made the task harder or caused extra vibe coding rounds.
+
+Good opening questions:
+
+- Which reusable decision was missing during this feature?
+- Should this live in a shared scope or stay local to one repository?
+- What trade-off are we trying to standardize?
+
+### 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.
+
+Use this checklist:
+
+1. Choose the right type: ADR for architecture, BDR for business, EDR for engineering practice.
+2. Choose the broadest safe scope; use `_local` only for repository-specific decisions.
+3. Pick the subject folder that best matches the topic.
+4. Write the context as a problem statement ending with a clear question.
+5. State one chosen outcome and the concrete implementation details.
+6. Add considered options only when the alternatives matter.
+7. Link to related XDRs, skills, and discussions instead of duplicating long instructions.
+
+### Promote it into shared documentation
+
+Once the decision is organized, move it from local discussion into a proposal that can be reviewed and published.
+
+The practical workflow is:
+
+1. Notice the gap during development, review, or specification.
+2. Check existing XDRs first to avoid duplicates or conflicts.
+3. Decide whether the guidance is shared or truly local.
+4. Draft a concise XDR proposal with the standard template.
+5. Ask the leaders responsible for that scope to review, adjust, and publish it.
+6. Update the relevant index and any related skills or articles.
+7. On later reviews, check whether big decisions are now covered well enough to keep the team near the 80% target.
+
+### How does this fit coding agents, vibe coding, and SDD?
+
+Coding agents are effective when durable guardrails already exist. Vibe-coding loops are useful for exploration, but if the same correction keeps being typed, the team is paying a documentation debt. SDD should keep feature-specific intent and acceptance criteria, while XDRs should hold reusable rules that must survive across features.
+
+### Practical rule of thumb
+
+If the same clarification would likely be needed in another feature, by another team, or by another agent, it is a good XDR candidate. Move it into an XDR when the guidance is reusable, stable enough to standardize, and broad enough to help future delivery.
+
+## 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
+- [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/.xdrs/index.md

@@ -28,5 +28,3 @@ Project-local XDRs that must not be shared with other contexts. Always keep this
 [View _local BDRs Index](_local/bdrs/index.md)
 
 [View _local ADRs Index](_local/adrs/index.md)
-
-[View _local EDRs Index](_local/edrs/index.md)

package/README.md

@@ -4,6 +4,8 @@ Curated distribution package of XDRs and speckit agent workflow files for AI-ass
 
 This collection is being updated as we develop applications and feel the need for new instructions and skills to help with AI agents.
 
+For guidance on turning recurring delivery friction into reusable decision records, see [Continuous XDR improvement](.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md).
+
 ## Getting Started
 
 This will extract all the features of agentme (skills, github configurations, speckit, xdrs collection):

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "",
   "dependencies": {
-    "filedist": "^0.24.0",
-    "xdrs-core": "^0.4.2"
+    "filedist": "^0.26.0",
+    "xdrs-core": "^0.7.1"
   },
   "bin": "bin/filedist.js",
   "files": [