Chore/update agent rules

[rgdevme]

No description provided.

[qodo-code-review]

PR Summary by Qodo

Compose AGENTS rules from modular .rules fragments

⚙️ Configuration changes 📝 Documentation 🕐 10-20 Minutes

AI Description

• Modularize agent rules into dedicated .rules/*.md fragments
• Configure agnos.json to compose AGENTS.md from rule fragments
• Fix docs metadata and clarify docs index/PRD titles

Diagram

graph TD
  A["agnos.json"] --> B(["agnos CLI / composer"]) --> C["AGENTS.md"]
  D[".rules/coding.md"] --> B
  E[".rules/git.md"] --> B
  F[".rules/secrets.md"] --> B
  G[".rules/docs.md"] --> B

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep a single monolithic AGENTS.md

• ➕ Simplest mental model (one file to edit/search)
• ➕ No composition tooling or mapping to maintain
• ➖ Harder to scale and review (large, mixed concerns)
• ➖ Higher chance of conflicting edits and accidental rule drift

2. Use a docs-site style config (YAML index + includes)

• ➕ More explicit ordering/sectioning than a flat list
• ➕ Can support grouping/versioning over time
• ➖ More custom convention to learn and enforce
• ➖ Still needs composition logic and validation

Recommendation: The PR’s approach (compose AGENTS.md from focused .rules fragments via agnos.json) is the best tradeoff: it keeps rules modular and reviewable while preserving a single canonical output for agent consumption. The main follow-up to consider is adding validation (e.g., missing frontmatter/title checks) to prevent malformed fragments from entering the composition set.

Files changed (7) +90 / -16

Documentation (2) +2 / -2

index.mdRename PRD link title in docs index +1/-1

Rename PRD link title in docs index

• Updates the docs index entry for the PRD to use the consistent “PRD — @luxia/agnos v0.1” display title.

.docs/index.md

prd.mdFix PRD frontmatter title field +1/-1

Fix PRD frontmatter title field

• Corrects the PRD frontmatter by removing an accidental markdown heading marker from the 'title' key so metadata parses cleanly.

.docs/plans/prd.md

Other (5) +88 / -14

coding.mdAdd frontmatter and slim coding rules to coding-only scope +3/-13

Add frontmatter and slim coding rules to coding-only scope

• Adds YAML frontmatter for consistent rule metadata. Removes branch/commit guidance from this file, aligning it to coding/package-manager standards only.

.rules/coding.md

docs.mdAdd documentation management rules +32/-0

Add documentation management rules

• Introduces documentation-specific standards: regeneration commands, OKF adherence, linking conventions, and when to update technical docs/decisions.

.rules/docs.md

git.mdAdd git/branch/commit/PR rules +26/-0

Add git/branch/commit/PR rules

• Centralizes git workflow guidance: linear history expectations, branch naming, conventional commits, and gh CLI usage constraints.

.rules/git.md

secrets.mdAdd secrets and env var handling rules +21/-0

Add secrets and env var handling rules

• Defines non-negotiable rules for not exposing secrets and for maintaining '.env.example' formatting/segmentation, plus guidance for '.env.agents' usage.

.rules/secrets.md

agnos.jsonCompose AGENTS.md rules from .rules fragments +6/-1

Compose AGENTS.md rules from .rules fragments

• Updates the rules composition mapping so AGENTS.md is built from individual rule fragments (coding, secrets, git, docs) instead of an empty list.

agnos.json

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📜 Skill insights (3)

Context used

✅ Compliance rules (platform): 64 rules

✅ Skills: doc-authoring, doc-authoring-with-logs

1. Manual edit to .docs/index.md 📜 Skill insight ≡ Correctness

Description

The PR directly modifies the docs-root index.md, which is designated as an autogenerated file and
must not be edited manually. This risks future regenerations overwriting the change and breaking the
documentation workflow contract.

Code

.docs/index.md[8]

+- [PRD — @luxia/agnos v0.1](plans/prd.md): Product requirements document for collapsing the 8-package monorepo into a single `@luxia/agnos` package and redesigning the domain model around config writers and a single config reader (agents).

Relevance

⭐⭐⭐ High

PR #30 added doc-authoring rule: “index.md is autogenerated… Never edit it by hand.”

PR-#30

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Compliance rule forbids manual edits to the docs-root index.md. The diff shows a direct content
change to .docs/index.md line 8.

.docs/index.md[8-8]
Skill: doc-authoring

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The docs-root index file (`.docs/index.md`) was manually edited, but it must be treated as autogenerated.

## Issue Context
Per documentation policy, `index.md` under the docs root must not be manually edited; it should be regenerated by the tooling.

## Fix Focus Areas
- .docs/index.md[8-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Em dash in .docs/index.md 📜 Skill insight ✧ Quality

Description

An em dash character (—) was introduced into documentation text, including the index entry and the
PRD frontmatter title. This violates the documentation style rule that prohibits em dashes.

Code

.docs/index.md[8]

+- [PRD — @luxia/agnos v0.1](plans/prd.md): Product requirements document for collapsing the 8-package monorepo into a single `@luxia/agnos` package and redesigning the domain model around config writers and a single config reader (agents).

Relevance

⭐⭐⭐ High

PR #30’s doc-authoring skill explicitly: “Do not use em dashes.”

PR-#30

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The compliance rule explicitly forbids em dashes in documentation, and the cited changed lines show
the text PRD — @luxia/agnos v0.1, which contains an em dash. This appears both in the
.docs/index.md index entry and in the .docs/plans/prd.md frontmatter title, directly
demonstrating the rule violation in each location.

.docs/index.md[8-8]
.docs/plans/prd.md[3-3]
Skill: doc-authoring

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Documentation must not contain em dashes (`—`), but the updated index entry and the PRD frontmatter title include one.

## Issue Context
Replace `—` with an allowed punctuation style (e.g., `-` or `:`) while preserving the same meaning in both places.

## Fix Focus Areas
- .docs/index.md[8-8]
- .docs/plans/prd.md[3-3]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. PRD timestamp not updated 📜 Skill insight ≡ Correctness

Description

.docs/plans/prd.md was modified, but its frontmatter timestamp was not updated to reflect the
current change. This breaks the requirement that document edits must bump the frontmatter timestamp.

Code

.docs/plans/prd.md[3]

+title: PRD — @luxia/agnos v0.1

Relevance

⭐⭐⭐ High

PR #30’s doc-authoring skill: “Update timestamp… whenever you change a document.”

PR-#30

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The checklist requires updating the frontmatter timestamp whenever a document is changed. The PR
modifies the PRD title line, while the file’s timestamp remains at 2026-06-30T00:00:00Z in the
current branch content.

.docs/plans/prd.md[3-3]
.docs/plans/prd.md[7-7]
Skill: doc-authoring

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR updates `.docs/plans/prd.md` content but does not update the YAML frontmatter `timestamp` to reflect the change time.

## Issue Context
Today is 2026-07-01; the file still shows `timestamp: 2026-06-30T00:00:00Z`.

## Fix Focus Areas
- .docs/plans/prd.md[1-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Broken spec links 🐞 Bug ⚙ Maintainability

Description

.rules/git.md links to the Conventional Branches/Commits specs without a URL scheme, so Markdown
will treat them as relative links and they won’t navigate to the intended external sites.

Code

.rules/git.md[R14-20]

+- Strictly adhere to **[conventional branches](conventionalbranch.org/#specification)**.
+- Branch names can never be called `<ai-agent-name>/*`. They have to strictly follow the conventional names.
+
+### Commit strategy
+
+- Strictly adhere to **[conventional commits](conventionalcommits.org/en/v1.0.0/#specification)**
+- - Conventional multi-line messages: subject < 70 chars in imperative mood; body explains why.

Relevance

⭐⭐ Medium

No historical evidence found for enforcing URL scheme in Markdown links (new .rules files not on
default branch).

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The rules document contains external links missing the URL scheme, which makes them relative instead
of absolute URLs in Markdown.

.rules/git.md[13-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`.rules/git.md` uses external links without a URL scheme (e.g. `conventionalcommits.org/...`). In Markdown these are treated as relative links, so clicking them won’t open the external spec pages.

### Issue Context
These files are injected into the canonical rules file (e.g. `AGENTS.md`), so broken links propagate into the generated rules.

### Fix Focus Areas
- .rules/git.md[14-20]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Malformed commit bullet 🐞 Bug ⚙ Maintainability

Description

.rules/git.md contains a - - ... list item, which renders as an empty bullet with a nested
bullet (or otherwise malformed), reducing readability and potentially confusing Markdown-to-text
renderers.

Code

.rules/git.md[R19-22]

+- Strictly adhere to **[conventional commits](conventionalcommits.org/en/v1.0.0/#specification)**
+- - Conventional multi-line messages: subject < 70 chars in imperative mood; body explains why.
+- Always group related changes logically and split unrelated work. Do not do a big single commit. Do not commit atomically.
+- Never amend pushed commits without explicit approval. Never --no-verify.

Relevance

⭐⭐ Medium

No historical evidence found for rejecting malformed “- -” Markdown bullets in rules/docs.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The double-dash list marker is present in the file and is not valid as a single bullet item.

.rules/git.md[17-22]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The commit-strategy section has a malformed list item (`- - Conventional ...`) which renders incorrectly.

### Issue Context
This is a generated/injected rules fragment; formatting issues propagate into the canonical rules output.

### Fix Focus Areas
- .rules/git.md[19-22]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Typoed secrets title 🐞 Bug ⚙ Maintainability

Description

.rules/secrets.md misspells “environment” in its frontmatter title, and that title is used by the
rules injector to generate the section heading/slug, propagating the typo into the canonical rules
output.

Code

.rules/secrets.md[R1-3]

+---
+title: Secrets and environmet variables
+---

Relevance

⭐⭐ Medium

No historical evidence found for fixing frontmatter-title typos in rules fragments (new .rules
path).

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The fragment title is misspelled, and the rules injection pipeline explicitly reads title from
frontmatter and uses it to slugify and render ## <title> sections.

.rules/secrets.md[1-3]
src/domains/rules/index.ts[31-37]
src/domains/rules/inject.ts[26-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The frontmatter title in `.rules/secrets.md` contains a typo (`environmet`). The rules injector uses this title to render the `## <title>` section header, so the typo becomes part of generated `AGENTS.md` content.

### Issue Context
Rules fragments are parsed with `gray-matter` and then rendered as H2 headings via the injector.

### Fix Focus Areas
- .rules/secrets.md[1-3]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Manual edit to .docs/index.md 📜 Skill insight ≡ Correctness

The PR directly modifies the docs-root index.md, which is designated as an autogenerated file and
must not be edited manually. This risks future regenerations overwriting the change and breaking the
documentation workflow contract.

Agent Prompt

## Issue description
The docs-root index file (`.docs/index.md`) was manually edited, but it must be treated as autogenerated.

## Issue Context
Per documentation policy, `index.md` under the docs root must not be manually edited; it should be regenerated by the tooling.

## Fix Focus Areas
- .docs/index.md[8-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Em dash in .docs/index.md 📜 Skill insight ✧ Quality

An em dash character (—) was introduced into documentation text, including the index entry and the
PRD frontmatter title. This violates the documentation style rule that prohibits em dashes.

Agent Prompt

## Issue description
Documentation must not contain em dashes (`—`), but the updated index entry and the PRD frontmatter title include one.

## Issue Context
Replace `—` with an allowed punctuation style (e.g., `-` or `:`) while preserving the same meaning in both places.

## Fix Focus Areas
- .docs/index.md[8-8]
- .docs/plans/prd.md[3-3]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

3. Prd timestamp not updated 📜 Skill insight ≡ Correctness

.docs/plans/prd.md was modified, but its frontmatter timestamp was not updated to reflect the
current change. This breaks the requirement that document edits must bump the frontmatter timestamp.

Agent Prompt

## Issue description
The PR updates `.docs/plans/prd.md` content but does not update the YAML frontmatter `timestamp` to reflect the change time.

## Issue Context
Today is 2026-07-01; the file still shows `timestamp: 2026-06-30T00:00:00Z`.

## Fix Focus Areas
- .docs/plans/prd.md[1-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

4. Broken spec links 🐞 Bug ⚙ Maintainability

.rules/git.md links to the Conventional Branches/Commits specs without a URL scheme, so Markdown
will treat them as relative links and they won’t navigate to the intended external sites.

Agent Prompt

### Issue description
`.rules/git.md` uses external links without a URL scheme (e.g. `conventionalcommits.org/...`). In Markdown these are treated as relative links, so clicking them won’t open the external spec pages.

### Issue Context
These files are injected into the canonical rules file (e.g. `AGENTS.md`), so broken links propagate into the generated rules.

### Fix Focus Areas
- .rules/git.md[14-20]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

5. Malformed commit bullet 🐞 Bug ⚙ Maintainability

.rules/git.md contains a - - ... list item, which renders as an empty bullet with a nested
bullet (or otherwise malformed), reducing readability and potentially confusing Markdown-to-text
renderers.

Agent Prompt

### Issue description
The commit-strategy section has a malformed list item (`- - Conventional ...`) which renders incorrectly.

### Issue Context
This is a generated/injected rules fragment; formatting issues propagate into the canonical rules output.

### Fix Focus Areas
- .rules/git.md[19-22]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

6. Typoed secrets title 🐞 Bug ⚙ Maintainability

.rules/secrets.md misspells “environment” in its frontmatter title, and that title is used by the
rules injector to generate the section heading/slug, propagating the typo into the canonical rules
output.

Agent Prompt

### Issue description
The frontmatter title in `.rules/secrets.md` contains a typo (`environmet`). The rules injector uses this title to render the `## <title>` section header, so the typo becomes part of generated `AGENTS.md` content.

### Issue Context
Rules fragments are parsed with `gray-matter` and then rendered as H2 headings via the injector.

### Fix Focus Areas
- .rules/secrets.md[1-3]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools