[knihit]

Description

The constraints skill reaches an agent only when the agent loads it. context/k-core-rules.md is always loaded by all 11 agents, so the general engineering practices now live there and the skill keeps only the workflow rules.

Context:

• context/k-core-rules.md: added an ## Engineering practices section after Writing habits, with 8 one-line rules: read the whole file before editing, follow codebase patterns, keep backward compatibility unless the user approves a break, comment the why, structured logging with correlation IDs when adding or changing logging in service code (other code follows its existing logging style), research first when the cause chain is unclear, say whether an unverified claim that matters is documented, inferred, or a guess, and confirm tests pass before calling a code change done. Because every agent loads these, the last two are scoped: non-code agents have no tests to confirm, and an orchestrator gets test evidence from the specialist rather than running tests, which its routing rules forbid. NEVER DO and Writing habits are unchanged.

Skills:

• skills/constraints/SKILL.md: ALWAYS 1, 2, 4, 5, 6, 7, Unknown Systems, and Acknowledge Uncertainty now point at the core rules instead of restating them, so there is one copy of each rule. Maker-checker, severity ordering, the 2-strike circuit breaker, and the Quality Gate tiers stay in the skill.
• constraints description: kept the MUST USE for every interaction first sentence, because feat(synth): add each Kiro agent's skills and a use rule to its prompt #120 classifies always-apply skills by that prefix and tests it for constraints. Rewrote the second sentence, which claimed the skill defines rules that now live in the core rules.

Docs:

• CHANGELOG.md: one bullet under [Unreleased] / ### Changed. No VERSION bump.
• User guide (concepts.md, faq.md, appendix/contributing.md, skills.md): the core rules are now described as NEVER DO, writing habits, and engineering practices, and the constraints row lists what the skill keeps. The four matching entries in tools/build-user-guide/sync-html-content.py now take the current bundle text as old; both HTML bundles and the manifest are regenerated.

Type of Change

• Modify existing skill
• Context / system prompt update

Testing

• npm test: 119 of 136 pass. The same 17 tests fail on main (bb7ef9c) with identical output; they need scripts/brand-config/lib/constants.js, which is not in the tree. This PR does not touch them.

• cd cli && make test: 1779 passed, 0 failed. The first run hit the known macOS flake in resolve_cwd_json_envelope; that test passed 3 of 3 in isolation and the full rerun passed. cli/ is unchanged.

• make build and make synth: ok, wrote 11 agents, 82 skills, 19 SOPs, 2 context files. The new section is in all 11 Claude Code agents; Kiro CLI v2 and v3 agents reference file://context/k-core-rules.md and the shipped context copy matches the source.

• make test-skills-sh (10 passed), make claude-plugin-check (ok), make test-py (222 passed), make kiro-power-check (ok, shellcheck skipped).

• Size: +859 bytes per agent, 9449 bytes across 11 agents. Claude Code agents each grow by 859 bytes (core rules are inlined); Kiro agent JSONs are byte-identical and the shared context file grows by 859 bytes. The bench below ran at +592 bytes, before the review fixes added read-before-edit and scoped two rules.

• Trial merges with fix(orchestrator): tighten the direct-work rules #114 and feat(synth): add each Kiro agent's skills and a use rule to its prompt #120: clean. With fix(orchestrator): tighten the direct-work rules #114 on top, section order in k-core-rules.md stays NEVER DO, Writing habits, Engineering practices.

• Benchmark: no-regression bench, main vs this branch, using the isolated harness from feat(orchestrator): mid-task delegation and same-type parallel spawns #95 (fresh fixture and isolated home per run, telemetry off). Claude Code 2.1.310 and Kiro CLI 2.35.1, 2 reps per cell, 32 runs, all intact. I used that harness instead of npm run benchmark so the results compare directly with feat(orchestrator): mid-task delegation and same-type parallel spawns #95.

  Harness	Scenario	Pass (main; branch)	Spawns (main; branch)	Cost (main; branch)
  Claude Code	U1 trivial lookup	2/2; 2/2	0, 0; 0, 0	$0.17; $0.15
  Claude Code	S3 capability gap	2/2; 1/2	1, 1; 1, 1	$0.32; $0.33
  Claude Code	S2 shared file	2/2; 2/2	3, 3; 2, 2	$2.19; $1.56
  Claude Code	P1 parallel parts	2/2; 2/2 rescored	4, 2; 2, 2	$2.39; $1.61
  Kiro CLI	U1 trivial lookup	2/2; 2/2	0, 0; 0, 0	1.23; 1.46 credits
  Kiro CLI	S3 capability gap	2/2; 2/2	1, 1; 1, 1	3.64; 4.26 credits
  Kiro CLI	S2 shared file	2/2; 2/2	2, 3; 2, 2	8.48; 8.45 credits
  Kiro CLI	P1 parallel parts	2/2; 2/2	2, 3; 3, 3	9.28; 10.01 credits

  • Trivial lookups did not get heavier: Claude Code U1 input grew about 740 tokens on a 142k prompt (0.5%), with 0 spawns on both. Kiro U1 rep 2 matched main; rep 1 used 0.84 credits and did not repeat.
  • Branch P1 rep 1 was a scorer miss: an added log line broke the scorer's unittest output parser. Run by hand, the tests pass, so it rescores to 2/2.
  • Branch S3 rep 1 was a real partial miss (correct answer, incomplete explanation). This scenario has been noisy before: both main runs failed it in the feat(orchestrator): mid-task delegation and same-type parallel spawns #95 bench.
  • 2 reps cannot detect small effects. This shows no large regression, not an improvement.
  • The Kiro CLI branch used about 7% more credits in total. Per-session logs show the same 20 agent sessions on both sides, with no workflows or extra spawns. The added section accounts for about 0.10 credits, and the rest is run-to-run variance (2 reps, not significant).

• make guide-check: the one failure (config listed in WITHDRAWN_COMMANDS but gone from cli/README.md) also fails on the branch before the docs commit; this PR does not touch it. bash tools/build-user-guide/build-user-guide.sh --check: ok.

• No new code files, so no SPDX headers needed.

Checklist

• My code follows the style guidelines of this project (see AGENTS.md's Code Style & Conventions)
• I have performed a self-review of my own changes
• I have made corresponding changes to the documentation
• My changes generate no new warnings

Agents Affected

All 11 agents load k-core-rules.md, so all of them get the new section.

• konductor
• konductor-mux-orchestrator
• konductor-cmux-orchestrator
• k-developer
• k-architect
• k-researcher
• k-product-manager
• k-quality-assurance
• k-tpm
• k-browser
• k-media-analyzer

Notes for Reviewers

• The structured logging rule keeps its service-code scope: it applies when an agent adds or changes logging in service code. Scripts, CLIs, and tests follow the codebase's existing logging style. Limiting it to added or changed logging keeps an always-loaded rule from pushing logging changes into unrelated tasks.
• Only CHANGELOG.md overlaps with feat(synth): add each Kiro agent's skills and a use rule to its prompt #120.