Skip to content

fix: respect conversation language across all harnesses#353

Open
masamaru0513 wants to merge 2 commits into
awslabs:v2from
masamaru0513:fix/v2-language-convention
Open

fix: respect conversation language across all harnesses#353
masamaru0513 wants to merge 2 commits into
awslabs:v2from
masamaru0513:fix/v2-language-convention

Conversation

@masamaru0513

@masamaru0513 masamaru0513 commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Adds a conversation-language rule to core/memory/org.md so all harnesses instruct agents to write human-readable artifacts in the user's language. Rebased onto the current v2 architecture (the pre-v2 persona-prompt-augment.yaml and conventions/ are gone).

Fixes #288

Summary

Adds a Conversation language rule to the ## Mandated section of core/memory/org.md. The rule states a principle: anything a person reads or reviews follows the conversation language; only machine-parsed/verified content stays English (stable IDs, enum values, code, file paths, mermaid keywords, template section headings, state files). One byte-shared source propagates to all four harnesses (claude, codex, kiro, kiro-ide) via bun scripts/package.ts.

This is feedforward prose — it does not guarantee 100% enforcement (no sensor checks output language). But in practice the presence or absence of the rule makes a large, consistent difference.

Changes

  • core/memory/org.md: added conversation-language rule to ## Mandated
  • core/tools/aidlc-version.ts: version bump 2.1.1 → 2.1.2
  • README.md: version badge updated
  • CHANGELOG.md: added ## [2.1.2] entry
  • dist/ (4 harnesses): regenerated via bun scripts/package.ts

User experience

Before (no rule):

Harness Behaviour
Claude Code Artifacts and chat dialogue fully English from the first stage, even when the user types in Japanese
kiro-cli Bodies mostly Japanese, but English leaks into secondary prose, sub-agent (reviewer) output, and design-spec files (interaction-spec, design-system-mapping, accessibility-checklist)

After (with this change):

Harness Behaviour
Claude Code Same artifacts and dialogue fully in the user's language; IDs / code / paths stay English
kiro-cli Previously leaking files now render in the user's language; machine tokens stay English

Verification

Ran the same Japanese prompt (簡単なTODOアプリを作りたい) on clean v2 (no rule) vs this change, on both kiro-cli and Claude Code. The control isolates the rule as the only variable — the before/after table above summarises the results.

Checklist

  • I have reviewed the contributing guidelines
  • Edited hand-authored source in core/, not dist/
  • Ran bun scripts/package.ts and committed regenerated dist/
  • bun scripts/package.ts --check reports no drift
  • Version bumped (core/tools/aidlc-version.ts + README badge + CHANGELOG entry)

@masamaru0513

Copy link
Copy Markdown
Contributor Author

@raj-jain-aws This is the v2 rebuild of #290 (now closed), reshaped onto the current v2 structure as you suggested. Source-only, no dist/ changes. I've posted the full before/after test results on #288. Would appreciate a review when you have a chance — thanks! 🙏

@wowzoo

wowzoo commented Jun 14, 2026

Copy link
Copy Markdown

Same on the v2 branch with Korean intents. Across 4 independent dry-run fixtures (different intent shapes — greenfield SaaS, a feature add on an existing service, a consumer-app MVP, a local-only full-stack service) the persona-authored artifacts under each intent's stages/ directory came out in English even though the human's prompts and pre-supplied PRDs were entirely in Korean. Korean only survived in verbatim quotes of human input.

Glad to see this PR — happy to test it against the four Korean fixtures once it merges.

@masamaru0513 masamaru0513 force-pushed the fix/v2-language-convention branch from 5b12844 to c53929a Compare June 27, 2026 04:22
masamaru0513 added a commit to masamaru0513/aidlc-workflows that referenced this pull request Jun 27, 2026
Add a conversation-language rule to the Mandated section of
core/memory/org.md so the framework default — inherited by all four
harnesses (claude, codex, kiro, kiro-ide) through the shared memory
layer — instructs agents to write every human-readable artifact in the
language the human last used.

The rule states a principle rather than an enumerated allow-list:
anything a person reads or reviews (requirements, stories, plans,
specs, reviews, questions, discovered practices, discovered/affirmed
rules, evidence, rationale) follows the conversation language, and only
machine-parsed/verified content stays English (stable IDs, enum values,
code, paths, mermaid keywords, template section headings matched by the
required-sections sensor, and machine-read state files). Rule-layer
artifacts following an ALWAYS/NEVER directive shape are written in the
human's language too; the marker keyword may stay.

Verified on the kiro harness end-to-end: ideation through operation
artifacts render in Japanese while IDs, code, tool names, template
headings, and state/audit files stay English.

Bumps version 2.1.1 -> 2.1.2 with matching README badge and CHANGELOG.
@masamaru0513 masamaru0513 changed the title fix: respect conversation language in generated files (v2) fix: respect conversation language across all harnesses Jun 27, 2026
@masamaru0513 masamaru0513 changed the base branch from v2_backup to v2 June 27, 2026 04:23
@masamaru0513

masamaru0513 commented Jun 27, 2026

Copy link
Copy Markdown
Contributor Author

Update (2026-06-27): Rebased and reworked for the v2-unified architecture (introduced 2026-06-15 in 7b824b3; core/memory/ finalized in 2.1.0, e713c4f 2026-06-24). See updated PR description for details.

  • Base changed v2_backupv2. The diff is now just the single source
    change to core/memory/org.md plus its regenerated dist/ — 16 files,
    +21/-24.
  • Reworked for the current v2 architecture. The rule lives in the shared
    core/memory/ method tree; the pre-v2 persona-prompt-augment.yaml and
    conventions/ are gone, so one byte-shared source now covers all four
    harnesses (claude, codex, kiro, kiro-ide) via bun scripts/package.ts.
  • Verified on both kiro-cli and Claude Code against a clean-v2 control —
    before/after table is in the description.
  • Version bumped 2.1.1 → 2.1.2 with matching README badge + CHANGELOG entry;
    bun scripts/package.ts --check and t68-version-changelog-sync pass.

@masamaru0513 masamaru0513 force-pushed the fix/v2-language-convention branch from c53929a to 445fd88 Compare July 1, 2026 04:01
masamaru0513 added a commit to masamaru0513/aidlc-workflows that referenced this pull request Jul 1, 2026
Add a conversation-language rule to the Mandated section of
core/memory/org.md so the framework default — inherited by all four
harnesses (claude, codex, kiro, kiro-ide) through the shared memory
layer — instructs agents to write every human-readable artifact in the
language the human last used.

The rule states a principle rather than an enumerated allow-list:
anything a person reads or reviews (requirements, stories, plans,
specs, reviews, questions, discovered practices, discovered/affirmed
rules, evidence, rationale) follows the conversation language, and only
machine-parsed/verified content stays English (stable IDs, enum values,
code, paths, mermaid keywords, template section headings matched by the
required-sections sensor, and machine-read state files). Rule-layer
artifacts following an ALWAYS/NEVER directive shape are written in the
human's language too; the marker keyword may stay.

Verified on the kiro harness end-to-end: ideation through operation
artifacts render in Japanese while IDs, code, tool names, template
headings, and state/audit files stay English.

Bumps version 2.1.1 -> 2.1.2 with matching README badge and CHANGELOG.
masamaru0513 added a commit to masamaru0513/aidlc-workflows that referenced this pull request Jul 1, 2026
Add a conversation-language rule to the Mandated section of
core/memory/org.md so the framework default — inherited by all four
harnesses (claude, codex, kiro, kiro-ide) through the shared memory
layer — instructs agents to write every human-readable artifact in the
language the human last used.

The rule states a principle rather than an enumerated allow-list:
anything a person reads or reviews (requirements, stories, plans,
specs, reviews, questions, discovered practices, discovered/affirmed
rules, evidence, rationale) follows the conversation language, and only
machine-parsed/verified content stays English (stable IDs, enum values,
code, paths, mermaid keywords, template section headings matched by the
required-sections sensor, and machine-read state files). Rule-layer
artifacts following an ALWAYS/NEVER directive shape are written in the
human's language too; the marker keyword may stay.

Verified on the kiro harness end-to-end: ideation through operation
artifacts render in Japanese while IDs, code, tool names, template
headings, and state/audit files stay English.

Bumps version 2.1.1 -> 2.1.2 with matching README badge and CHANGELOG.
@masamaru0513 masamaru0513 force-pushed the fix/v2-language-convention branch from 445fd88 to d94506d Compare July 1, 2026 13:49
Add a conversation-language rule to the Mandated section of
core/memory/org.md so the framework default — inherited by all four
harnesses (claude, codex, kiro, kiro-ide) through the shared memory
layer — instructs agents to write every human-readable artifact in the
language the human last used.

The rule states a principle rather than an enumerated allow-list:
anything a person reads or reviews (requirements, stories, plans,
specs, reviews, questions, discovered practices, discovered/affirmed
rules, evidence, rationale) follows the conversation language, and only
machine-parsed/verified content stays English (stable IDs, enum values,
code, paths, mermaid keywords, template section headings matched by the
required-sections sensor, and machine-read state files). Rule-layer
artifacts following an ALWAYS/NEVER directive shape are written in the
human's language too; the marker keyword may stay.

Verified on the kiro harness end-to-end: ideation through operation
artifacts render in Japanese while IDs, code, tool names, template
headings, and state/audit files stay English.

Bumps version 2.1.4 -> 2.1.5 with matching README badge and CHANGELOG.
@masamaru0513 masamaru0513 force-pushed the fix/v2-language-convention branch from d94506d to 04d48be Compare July 1, 2026 13:57
@masamaru0513

Copy link
Copy Markdown
Contributor Author

Update (2026-07-01): Rebased onto the latest v2 (now at 2.1.4) to pick up #443#448 and #465. The change itself is unchanged — the conversation-language rule in core/memory/org.md plus its regenerated dist/. Re-bumped the version 2.1.4 → 2.1.5 (following the same convention as the recent releases: aidlc-version.ts across all harnesses + README badge + a numbered ## [2.1.5] CHANGELOG heading), since the earlier 2.1.2 bump was superseded by the releases that landed in the meantime. t68-version-changelog-sync passes. Happy to re-bump again if it collides with another release before merge.

…ntion

# Conflicts:
#	CHANGELOG.md
#	README.md
#	core/tools/aidlc-version.ts
#	dist/claude/.claude/tools/aidlc-version.ts
#	dist/codex/.codex/tools/aidlc-version.ts
#	dist/kiro-ide/.kiro/tools/aidlc-version.ts
#	dist/kiro/.kiro/tools/aidlc-version.ts
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.

2 participants