diff --git a/CHANGELOG.md b/CHANGELOG.md index ded3c1bc..24a5e102 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ not per individual commit. ### Changed +- The always-loaded core rules now carry the engineering practices from the `constraints` skill, + so agents get them without loading the skill. - The orchestrators (`konductor`, `konductor-mux-orchestrator`, `konductor-cmux-orchestrator`) may now read files, search the codebase, run read-only shell commands, and answer lookup questions themselves instead of spawning a specialist for each. One table in diff --git a/context/k-core-rules.md b/context/k-core-rules.md index f0446b71..c4dfea2f 100644 --- a/context/k-core-rules.md +++ b/context/k-core-rules.md @@ -18,3 +18,14 @@ These rules apply to every Konductor agent in every interaction. Violating a NEV ## Writing habits In sentences you write or rewrite, do not use em or en dashes, AI vocabulary, or filler, even when nearby text does (see the `humanize-writing` skill for how to rewrite them). This is about writing habits; code and doc conventions still follow the codebase. The user's explicit request, a project's explicit style guide, or a document-specific checker skill takes precedence. Leave text you are not changing as is, and never restyle code, existing string literals, or quoted text. + +## Engineering practices + +- Read the whole file before you edit it. +- Follow the patterns and conventions already in the codebase. +- Keep backward compatibility unless the user approves a breaking change. +- Comment non-obvious logic with the why, not the what. +- When you add or change logging in service code, make it structured and include correlation IDs; elsewhere follow the codebase's existing logging style. +- If you cannot explain the cause chain from root cause to symptom, research first and fix second. +- When a claim matters to a decision and you have not verified it, say whether it rests on documented knowledge (you read the code or docs), inference, or a guess. +- Before calling a code change done, confirm the tests pass, not only that the code compiles. An orchestrator gets that evidence from the specialist rather than running the tests. diff --git a/docs/index.html b/docs/index.html index fe428588..7cbb65b5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -390,7 +390,7 @@

An agent team that ships the whole lifecycle.

\ No newline at end of file diff --git a/docs/site/.user-guide.manifest b/docs/site/.user-guide.manifest index 34ac1d8c..818cbfdf 100644 --- a/docs/site/.user-guide.manifest +++ b/docs/site/.user-guide.manifest @@ -1,6 +1,6 @@ # Generated by tools/build-user-guide/build-user-guide.sh — do not edit. -content_sha256=1f27c530f1d309023e979c2098f6050628e99f94fcc0c22fd0d54924e44bf32d -built_at=2026-09-23T15:08:36Z +content_sha256=1f85073f3659dbc0aa0ac9dad598a1da717bdff87b33962e7c5943594343f2c1 +built_at=2026-10-28T16:42:30Z runtime=deterministic -source_commit=6a5b6f0e93330f0baffe85427f81edca8d0d677b -output_sha256=9aae3ee3ccf9fa2b46f3afee49bf3f45d303030df19e0010af68177d79e9076c +source_commit=e778319fd6056ce92044a4ea35c0b59c0d6a2615 +output_sha256=e4ccdae2c25d9827f180752fd4e979bbcf1f695c716b7ef5fd8005afcad80641 diff --git a/docs/site/user-guide.html b/docs/site/user-guide.html index fe428588..7cbb65b5 100644 --- a/docs/site/user-guide.html +++ b/docs/site/user-guide.html @@ -390,7 +390,7 @@

An agent team that ships the whole lifecycle.

\ No newline at end of file diff --git a/docs/user-guide/appendix/contributing.md b/docs/user-guide/appendix/contributing.md index 4ce41b23..9828584a 100644 --- a/docs/user-guide/appendix/contributing.md +++ b/docs/user-guide/appendix/contributing.md @@ -30,7 +30,7 @@ Five files control five different things. Pick the smallest one that achieves wh | Change | Edit | Effect | | --- | --- | --- | -| Rules every agent must follow | `context/k-core-rules.md` | NEVER DO rules and writing habits, loaded at session start for every agent | +| Rules every agent must follow | `context/k-core-rules.md` | NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent | | Which specialist handles which kind of request | `context/k-orchestrator-routing-rules.md` | Routing, loaded at session start for all three orchestrators | | The steps of one workflow | `agent-sops/.sop.md` | That SOP's steps, constraints, and quality gates | | How an agent reasons about one topic | `skills//SKILL.md` | Guidance that agent loads on demand | diff --git a/docs/user-guide/concepts.md b/docs/user-guide/concepts.md index dc8bb073..8f327595 100644 --- a/docs/user-guide/concepts.md +++ b/docs/user-guide/concepts.md @@ -153,8 +153,8 @@ A **context file** is Markdown loaded into an agent's memory *at session start* active for the whole session — unlike a skill, which loads on demand. Context files are for rules that must never be missed. -There are two today. `context/k-core-rules.md` holds the NEVER DO rules and the writing-habits -rule, and all 11 agents load it. `context/k-orchestrator-routing-rules.md` is loaded by all three +There are two today. `context/k-core-rules.md` holds the NEVER DO rules, the writing-habits +rule, and the engineering practices, and all 11 agents load it. `context/k-orchestrator-routing-rules.md` is loaded by all three orchestrators. The routing rules file contains the capability-to-agent routing table and three `[CODE RED]` rules, including this one: diff --git a/docs/user-guide/faq.md b/docs/user-guide/faq.md index db69326c..f2bb322d 100644 --- a/docs/user-guide/faq.md +++ b/docs/user-guide/faq.md @@ -134,7 +134,7 @@ Common edits, in ascending order of blast radius: | Edit | File | Effect | | --- | --- | --- | -| Change the core rules | `context/k-core-rules.md` | NEVER DO rules and writing habits, loaded at session start for every agent | +| Change the core rules | `context/k-core-rules.md` | NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent | | Change routing | `context/k-orchestrator-routing-rules.md` | Which specialist gets which kind of request | | Change a procedure | `agent-sops/.sop.md` | The steps, constraints, and gates of one workflow | | Change knowledge | `skills//SKILL.md` | How an agent reasons about one topic | diff --git a/docs/user-guide/skills.md b/docs/user-guide/skills.md index cbc093d7..23a5b7f4 100644 --- a/docs/user-guide/skills.md +++ b/docs/user-guide/skills.md @@ -42,7 +42,7 @@ Loaded to shape *how* an agent works rather than what it produces. Several are o | Skill | What it does | Reach for it when | Declared by | | --- | --- | --- | --- | -| `constraints` | Hard behavioural rules for every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in `context/k-core-rules.md`. | You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand. | all 11 | +| `constraints` | Workflow rules for every agent: maker-checker validation, severity ordering, the 2-strike circuit breaker, and the quality gate. The NEVER DO rules, writing habits, and engineering practices live in `context/k-core-rules.md`. | You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand. | all 11 | | `about-konductor` | Gets a new user from nothing to a working session: the real `konductor` CLI command surface, example orchestrator prompts, and the agent/skill/SOP model. | Someone asks what this is, how to install it, or what they can ask for. Backs the SOP of the same name. | all 3 orchestrators | | `sop-state-management` | Session and checklist mechanics for long-running SOPs: minting or resuming a session by project identity, per-phase status, and serialized fix-cycle counters. | You are running or resuming `k-full-sdlc`. It owns the state file schema and the resume-discovery walk. | all 3 orchestrators | | `delegation-protocol` | The authoritative delegation format: the 8-field prompt (target agent + 7 sections), the agent registry, parallel-execution rules, and handoff patterns. | Read it to understand what the orchestrator sends a specialist. Edit it to change routing — it outranks the routing-rules context file. | all 3 orchestrators | diff --git a/skills/constraints/SKILL.md b/skills/constraints/SKILL.md index ae5a2da5..7ffb38e9 100644 --- a/skills/constraints/SKILL.md +++ b/skills/constraints/SKILL.md @@ -1,6 +1,6 @@ --- name: constraints -description: MUST USE for every interaction across all Konductor agents. Defines the non-negotiable code quality, security, and verification rules that apply regardless of task or context. +description: MUST USE for every interaction across all Konductor agents. Defines the maker-checker, quality gate, severity ordering, and failure recovery rules; the always-loaded core rules hold the rest. version: 1.0.0 tags: [skill, behavioral, constraints, quality, security] --- @@ -23,13 +23,13 @@ The NEVER DO rules live in the core rules, which every agent loads at session st ### ALWAYS DO -1. **Read before edit** — Always read the complete file before making changes -2. **Follow existing patterns** — Always match the conventions already in the codebase. Writing habits are covered in `k-core-rules`. +1. **Read before edit**: see Engineering practices in the core rules +2. **Follow existing patterns**: see Engineering practices and Writing habits in the core rules 3. **Maker-checker** — Always run the maker-checker pattern: generate artifact → validate with the corresponding checker skill before presenting to the user -4. **Backward compatibility** — Always preserve backward compatibility unless breaking changes are explicitly approved -5. **Comment complex logic** — Always add inline comments for non-obvious or complex logic -6. **Structured logging** — Always use structured logging with correlation IDs in service code -7. **Verify before done** — Always verify changes compile and tests pass before declaring a task complete +4. **Backward compatibility**: see Engineering practices in the core rules +5. **Comment complex logic**: see Engineering practices in the core rules +6. **Structured logging**: see Engineering practices in the core rules +7. **Verify before done**: see "No broken commits" and "No broken state" under NEVER DO, and Engineering practices, in the core rules 8. **Severity ordering** — Always present findings as CRITICAL → IMPORTANT → SUGGESTION ## Failure Recovery @@ -44,15 +44,11 @@ After 2 failed fix attempts for the same error, **STOP**. Do not attempt a third ### Unknown Systems -If you cannot explain the cause chain from root cause → symptom, **research FIRST, fix SECOND**. Do not guess at fixes for systems you don't understand. +See Engineering practices in the core rules: research first, fix second. ### Acknowledge Uncertainty -When responding, state whether you are working from: - -- **Documented knowledge** — you read the relevant code/docs -- **Inference** — you are reasoning from patterns but haven't verified -- **Guess** — you are speculating and the user should verify +See Engineering practices in the core rules: for an unverified claim that matters, say whether it rests on documented knowledge, inference, or a guess. ## Quality Gate diff --git a/tools/build-user-guide/sync-html-content.py b/tools/build-user-guide/sync-html-content.py index 88a31c1e..3e88c136 100755 --- a/tools/build-user-guide/sync-html-content.py +++ b/tools/build-user-guide/sync-html-content.py @@ -80,8 +80,8 @@ 'search/read, region list, and regional availability.'), # ---- every agent loads context/k-core-rules.md --------------------------- ("concepts context file paragraph", - "There is one today: context/k-orchestrator-routing-rules.md, loaded by all three orchestrators. It contains", - "There are two today. context/k-core-rules.md holds the NEVER DO rules and the writing-habits rule, and all 11 agents load it. context/k-orchestrator-routing-rules.md is loaded by all three orchestrators. The routing rules file contains"), + "There are two today. context/k-core-rules.md holds the NEVER DO rules and the writing-habits rule, and all 11 agents load it. context/k-orchestrator-routing-rules.md is loaded by all three orchestrators. The routing rules file contains", + "There are two today. context/k-core-rules.md holds the NEVER DO rules, the writing-habits rule, and the engineering practices, and all 11 agents load it. context/k-orchestrator-routing-rules.md is loaded by all three orchestrators. The routing rules file contains"), ("concepts context files row", '{ k: "Context files — 1", v: "The orchestrator routing rules, always active" }', '{ k: "Context files — 2", v: "The core rules for every agent and the orchestrator routing rules, always active" }'), @@ -100,14 +100,14 @@ ("troubleshooting context count", "it should report 1 registered.", "it should report 2 registered."), ("contributing: five files", "Four files control four different things.", "Five files control five different things."), ("contributing: core rules row", - 'h1: "EDIT", h2: "EFFECT", rows: [\n { k: "context/k-orchestrator-routing-rules.md", v: "Which specialist', - 'h1: "EDIT", h2: "EFFECT", rows: [\n { k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules and writing habits, loaded at session start for every agent" },\n { k: "context/k-orchestrator-routing-rules.md", v: "Which specialist'), + '{ k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules and writing habits, loaded at session start for every agent" }', + '{ k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent" }'), ("faq: core rules row", - 'rows: [\n { k: "context/k-orchestrator-routing-rules.md", v: "Change routing', - 'rows: [\n { k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules and writing habits loaded at session start for every agent" },\n { k: "context/k-orchestrator-routing-rules.md", v: "Change routing'), + '{ k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules and writing habits loaded at session start for every agent" }', + '{ k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules, writing habits, and engineering practices loaded at session start for every agent" }'), ("skills catalog: constraints row", - "every agent \u2014 what they must never and always do, across code quality, security, and verification.", - "every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in context/k-core-rules.md."), + "Hard behavioural rules for every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in context/k-core-rules.md.", + "Workflow rules for every agent: maker-checker validation, severity ordering, the 2-strike circuit breaker, and the quality gate. The NEVER DO rules, writing habits, and engineering practices live in context/k-core-rules.md."), ("skills catalog: constraints reach", "REACH FOR IT: Always on. You never invoke it; it is the floor every agent stands on.", "REACH FOR IT: You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand."),