Skip to content

fix(agents-md): list a scoped rule at the file a target writes, or embed it (0.8.3) - #23

Merged
llima merged 4 commits into
mainfrom
fix/cli-0-8-3
Oct 4, 2026
Merged

llima merged 4 commits into
mainfrom
fix/cli-0-8-3

Conversation

@llima

@llima llima commented Oct 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

This PR bumps the version to 0.8.3. Merging it publishes craftar@0.8.3 to npm once the release run is approved in the npm environment.

What changes. In 0.8.2, AGENTS.md listed every scoped rule (fileMatch, manual, auto) at .claude/rules/<name>.md, whatever the workspace's targets were. When no target wrote that file, the rule's text reached no agent and nothing warned. Now each scoped rule:

  • names .claude/rules/<name>.md when claude-code writes it;
  • otherwise names .kiro/steering/<name>.md when kiro writes it;
  • otherwise is embedded in full under > Scoped rule — <scope>.

The order of the workspace's targets does not matter. This follows the approved spec, scoped rules in AGENTS.md.

  • src/emitters/shared.ts gains ruleFile(target, meta), now used by the claude-code, kiro and agents-md emitters. As a result, the listed path cannot drift from what the writers write. The refactor is byte-neutral: every claude-code and kiro output is unchanged.
  • No new warning, no schema change, no change to plan(), status(), the lock or the CLI.

Which workspaces see update

Only AGENTS.md changes, and only in the cases below. The user approved this byte change at a checkpoint before the commit, using the before/after measured on 0.8.2 with the spec's six-rule Forge.

Workspace At the first sync on 0.8.3
has claude-code, scoped rules with the default targets (every workspace craftar import produced) no change
no scoped rule aimed at agents-md no change
kiro + agents-md, no claude-code each scoped line goes from .claude/rules/ to .kiro/steering/
agents-md only each scoped line is replaced by the embedded rule
a scoped rule whose own targets exclude claude-code that rule moves to .kiro/steering/ or is embedded

An affected workspace shows AGENTS.md as update, and craftar sync --check exits 1 until it syncs. The README has an Upgrading → to 0.8.3 note.

Tests

  • Three existing tests in test/emitters/agents-md.test.ts are re-targeted. As the spec requires, they now use ["claude-code", "agents-md"], and their expected AGENTS.md bytes are unchanged. That is the proof that state A does not move. One path-list assertion gains the .claude/rules/ files. No other existing test changed.
  • Eight new tests, each asserting exact bytes. Each was shown failing on the 0.8.2 emitter. They cover:
    • agents-md only;
    • kiro + agents-md;
    • all three targets;
    • claude-code + agents-md;
    • target order;
    • a variant;
    • sections in an embedded rule;
    • CRLF kept.

Out of scope

  • A .claude/rules/… reference inside a rule body is emitted as the Forge holds it. That reference is the next patch's subject.
  • A rule and a steering ingredient that write the same .kiro/steering/<name>.md collide as before. That case is warned (last wins), and it is not new.

Test plan

  • npm run typecheck: exit 0 on ad10cc2.
  • npm run build: exit 0. node bin/craftar.js --version prints 0.8.3.
  • vitest without test/ci.test.ts (Linux): 798 passed / 5 skipped.
  • Oracle: skipped. There is no fixture, and the user declined using a client workspace. Byte evidence:
    • test/golden/** is unchanged;
    • the reviewer's probe found claude-code and kiro outputs byte-identical to d65afff across 16 scenarios, and AGENTS.md identical in 13 state-A scenarios.
  • Reviews: node-cli-reviewer and docs-author round 1 were clean, with nits only.
  • CI green on this PR: 8 of 8 (ubuntu and windows × Node 22 and 24, runs 37232063445, 37232084434).

llima added 4 commits October 4, 2026 16:54
Add ruleFile() to shared.ts and use it in claude-code.ts and kiro.ts.
The path AGENTS.md will list is now computed by the same function for all three
emitters, preventing drift.
…bed them

Spec 14: a scoped rule names .claude/rules/ when claude-code writes it,
.kiro/steering/ when only kiro does, and is embedded with its scope when
no target writes it. Workspaces in state A keep their bytes.
…hat 0.8.3 changes

Update the Targets description for agents-md to specify where each scoped
rule is listed or when it is embedded. Add the 0.8.3 upgrade notes.
Bump version to 0.8.3 for the agents-md scoped-rules fix.
@llima
llima merged commit 417caeb into main Oct 4, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant