docs: some changes to sync agents review by alexgwolff · Pull Request #6 · strukit/kraf

alexgwolff · 2026-10-05T22:04:59Z

Signed-off-by: Alex G. Wolff 13754094+alexgwolff@users.noreply.github.com

Summary

Reorganize repository conventions and align agent guidance with the documentation.

What does this pull request change?

Rename BUILDING.md to GENERAL_CONVENTIONS.md and CODE_STANDARDS.md to CODE_CONVENTIONS.md; move test conventions into CODE_CONVENTIONS.md.
Expand AGENTS.md with documentation navigation, rule precedence, and agent behavior requirements; remove the docs skill.
Add invariants notes and revise documentation graph and platform naming guidance.
Update documentation indexes and references, relocate the example Intent, and reformat documentation.

How to test?

Review the changed documents against GENERAL_CONVENTIONS.md and SPEC_CONVENTIONS.md.
Check relative links, anchors, and navigation through the documentation and example set.
Automated tests were not run for this description update.

Other Notes and Links

No Rust implementation changes.
Review findings are tracked in the PR discussion.

Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com>

luisfmoraes

Review: 9 inline findings. The most important are the broken spec→intent link from the file move, and the Mac naming rule contradicting the _macos.rs convention and existing hits.

luisfmoraes · 2026-10-05T23:17:05Z

+This example does not define how configuration is stored, transmitted, or loaded
+— only that unknown keys are rejected.

 ## Documentation


Broken link. This file moved from docs/example-intent.md to docs/example/example-intent.md, but docs/example/example.spec.md:23 (not touched by this PR) still links to ../example-intent.md, which now resolves to docs/example-intent.md, a file that no longer exists. The spec's link back to its intent breaks, so the docs-review check fails on the example set.

Suggested fix: change that link in example.spec.md to ./example-intent.md (and check example.acceptance.md for the same link).

marcou no lugar errado nao tem link onde marcou

luisfmoraes · 2026-10-05T23:17:05Z

-Platform names MUST be written as `Linux`, `MacOS`, and `Windows` — in prose,
-docs, code, and diagrams. In particular, use `MacOS`; Apple's `macOS` styling
-MUST NOT be used.
+Platform names MUST be written as `Linux`, `Mac`, and `Windows` — in prose,


The MacOS → Mac rename is incomplete. This MUST covers "prose, docs, code, and diagrams", but existing hits on dev were not updated:

src/environment/src/env_var/docs/env-var-host/env-var-host.acceptance.md lines 35, 51 and 53 still say "MacOS mapping(s)"

code: MACOS_MAPPINGS, the env_var_host_macos module, src/main.rs:9

After merge, these break a MUST that this PR introduces. Either update the hits in the same PR, or narrow the rule to prose/docs and state how identifiers are spelled.

fora de escope analisar rust files nada tinha sido mexido no PR

mas a parte do docs esta certa

luisfmoraes · 2026-10-05T23:17:05Z

@@ -137,16 +145,16 @@ testable and reusable outside the CLI (another binary, another consumer, etc.).

 ### Multi-platform

-Every domain MUST be designed for multiple platforms (MacOS/Linux/Windows) from
+Every domain MUST be designed for multiple platforms (Mac/Linux/Windows) from
 the start, not bolted on later. Platform-specific code MUST be isolated (e.g.
 `_macos.rs`, `_linux.rs`, `_windows.rs`), and shared logic MUST stay separate


Contradicts the Platform names rule. This section requires platform files named _macos.rs, while Platform names says Mac MUST be used in code. A contributor adding a platform file must break one of the two: _mac.rs goes against this rule and every existing file, and _macos.rs goes against the naming rule. Suggest adding an explicit exception for identifiers and file names (e.g. "macos in snake_case/SCREAMING_CASE identifiers and cfg(target_os = \"macos\")").

fora de escope analisar rust files nada tinha sido mexido no PR

luisfmoraes · 2026-10-05T23:17:05Z

-standards — its constitution. You amend them through a pull request; you MUST
-NOT break them. A rule stated as a preference is still binding, and its
-exceptions are part of the rule.
-
 ## Overview


Removed sentence isn't restated anywhere. The old paragraph said: "A rule stated as a preference is still binding, and its exceptions are part of the rule." The new IMPORTANT callout doesn't carry this over. Without it, rules worded as preferences, e.g. Std-first's "Prefer Rust's standard library over external crates", read as optional, and their listed exceptions stop being part of the rule. Suggest keeping that sentence in the callout (or rewording such rules with MUST/SHOULD).

luisfmoraes · 2026-10-05T23:17:05Z

-path. Feature docs (intent, specification, acceptance, ADR) follow their own
-graph — see [Specifications](./SPEC_CONVENTIONS.md#docs-graph).
+Repo-level docs form a connected graph rooted at [README.md](../README.md):
+every doc MUST link to every other doc it references, so no doc is reachable


The Docs graph rule got weaker. It now only requires linking to docs you reference, so a new doc that references nothing and that nothing links to passes the rule while being reachable only by file path. That contradicts "connected graph rooted at README.md" just above. The explicit pointer to SPEC_CONVENTIONS.md#docs-graph for feature docs was also dropped here. AGENTS.md expects agents to reach rules by following links, so it's worth keeping.

luisfmoraes · 2026-10-05T23:17:05Z

+outbound links in one place. A set of docs MAY define its own graph; when it does, that graph MUST be
+documented alongside the set. Always read the graph before navigating or linking


Two small issues here:

"Always read the graph…" is not an RFC 2119 keyword, so it breaks this file's own rule that it "MUST NOT use alternative words … as normative keywords". Suggest "Agents SHOULD read the graph before…" (or MUST).

Line 112 is 101 characters. The rest of the PR is wrapped at 80 columns, so dprint (textWrap: always) will rewrap this paragraph on its next run and create churn in an unrelated PR.

Line 112 is 101 characters tem zero rule falando sobre isso

luisfmoraes · 2026-10-05T23:17:05Z

+---
+
+> [!IMPORTANT]
+> These are the Kraf codebase's **invariants** — non-negotiable rules that


This callout makes the whole architecture doc binding, but the doc describes itself as partly illustrative ("The names shown here (filesystem, read_file, local, ...) are illustrative, not a final inventory") and describes containers that don't exist yet (kraf-mcp, kraf-lib, kraf-host). Those placeholder names become invariants that code "MUST NOT break". Suggest scoping the callout, e.g. only the Dependency rule and Ports and adapters sections are invariants, and the diagrams and names are illustrative.

nao sei oque ele entendeu por Those placeholder names become invariants that code "MUST NOT break"

mas a pena revever pra ver se a linguagem nao esta clara

luisfmoraes · 2026-10-05T23:17:05Z


-This index links to Kraf's repository-wide documentation and illustrative
-specification examples. Feature documentation lives with the feature it describes.
+This index links to Kraf's repository-wide documentation.


Leftovers from removing the Examples section:

The front-matter summary (line 3) still says this index covers "specification examples".

docs/example/example-intent.md:32 still describes this page as "documentation index and example overview".

Agents that index by front-matter are sent here for examples this page no longer lists.

acho que muito longe isso nao sei blz inconsistencia mas né ..

luisfmoraes · 2026-10-05T23:17:05Z

-edits this file — it MUST NOT be an ad-hoc exception slipped into passing code.
+> [!IMPORTANT]
+> These are the Kraf codebase's **invariants** — non-negotiable rules that
+> codebase MUST follow. Treat them like a constitution: you MUST NOT break an


Nits on the invariants callout:

Grammar: "non-negotiable rules that codebase MUST follow" should be "that the codebase MUST follow".

The same 6-line callout is pasted into ARCHITECTURE, BUILDING, CODE_CONVENTIONS and SPEC_CONVENTIONS, so every wording change has to land in four places or the copies drift. Consider defining it once (e.g. in docs/README.md or BUILDING) and linking to it.

It replaced this doc's ## Overview, so the file now jumps straight from the callout to ## Rust modules with no intro.

Grammar: "non-negotiable rules that codebase MUST follow" should be "that the codebase MUST follow" pq?

The same 6-line callout is pasted into ARCHITECTURE, BUILDING, CODE_CONVENTIONS and SPEC_CONVENTIONS, so every wording change has to land in four places or the copies drift. Consider defining it once (e.g. in docs/README.md or BUILDING) and linking to it.

esta definido nos templates que é obrigatorio

Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com>

docs: some changes to sync agents review

c467747

Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com>

luisfmoraes reviewed Oct 5, 2026

View reviewed changes

alexgwolff force-pushed the docs/generic-agents branch 2 times, most recently from 7214599 to c467747 Compare October 6, 2026 20:34

alexgwolff added 2 commits October 6, 2026 22:59

temp

30bae32

Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com>

temp

7931d9c

Signed-off-by: Alex G. Wolff <13754094+alexgwolff@users.noreply.github.com>

		outbound links in one place. A set of docs MAY define its own graph; when it does, that graph MUST be
		documented alongside the set. Always read the graph before navigating or linking

Conversation

alexgwolff commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What does this pull request change?

How to test?

Other Notes and Links

Uh oh!

luisfmoraes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexgwolff commented Oct 5, 2026 •

edited

Loading