Skip to content

fix(guide): stop sync-html-content duplicating the Rust prerequisite row #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ihmaws merged 2 commits into from
Oct 20, 2026
Merged

fix(guide): stop sync-html-content duplicating the Rust prerequisite row #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff44ad4
fix(guide): stop sync-html-content duplicating the Rust prerequisite row
ihmaws Oct 14, 2026
1c0731a
fix(guide): update sync-html-content edits for claude-sonnet-5.5
ihmaws Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/index.html
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/site/user-guide.html
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions tools/build-user-guide/html_sop_edits.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,10 +173,10 @@
SOP_EDITS += [
("agents bullet: architect model",
"k-architect is the only agent on a different model (claude-opus-4.6) and carries 32 skills \u2014 nearly a third of the library.",
"k-architect carries 37 skills \u2014 close to half the library, and by far the largest share of any agent. Every agent runs the same model, claude-sonnet-5."),
"k-architect carries 37 skills \u2014 close to half the library, and by far the largest share of any agent. Every agent runs the same model, claude-sonnet-5.5."),
("specialists table: architect",
'{ k: "k-architect", v: "claude-opus-4.6, the only agent not on Sonnet. SOPs: k-design-doc-creation, k-existing-design-review, k-adversarial-pull-request-review. 32 skills.',
'{ k: "k-architect", v: "claude-sonnet-5, the model every agent runs. SOPs: k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review. 38 skills.'),
'{ k: "k-architect", v: "claude-sonnet-5.5, the model every agent runs. SOPs: k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review. 38 skills.'),
("specialists table: developer skills",
'{ k: "k-developer", v: "SOPs: k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow. 19 skills',
'{ k: "k-developer", v: "SOPs: k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow. 27 skills'),
Expand Down Expand Up @@ -766,7 +766,7 @@
"\n\n "),
("prerequisites: essentials gains a Rust row",
"<div style=\"display:grid;grid-template-columns:1.2fr 1.7fr 1.1fr\">\n <div style=\"padding:13px 16px;font-size:14.5px;font-weight:600\">A terminal</div>",
"<div style=\"display:grid;grid-template-columns:1.2fr 1.7fr 1.1fr;border-bottom:1px solid var(--bd)\">\n <div style=\"padding:13px 16px;font-size:14.5px;font-weight:600\">A Rust toolchain</div>\n <div style=\"padding:13px 16px;font-size:14.5px;line-height:1.55;color:var(--mu)\">No release has been published yet, so you build the CLI from a clone — rustup is the usual way to get one</div>\n <div style=\"padding:13px 16px;font-family:'JetBrains Mono',monospace;font-size:12px;color:var(--lav)\">cargo --version</div>\n </div>\n <div style=\"display:grid;grid-template-columns:1.2fr 1.7fr 1.1fr\">\n <div style=\"padding:13px 16px;font-size:14.5px;font-weight:600\">A terminal</div>"),
"<div style=\"display:grid;grid-template-columns:1.2fr 1.7fr 1.1fr;border-bottom:1px solid var(--bd)\">\n <div style=\"padding:13px 16px;font-size:14.5px;font-weight:600\">A Rust toolchain</div>\n <div style=\"padding:13px 16px;font-size:14.5px;line-height:1.55;color:var(--mu)\">Built from a clone of the repository — rustup is the usual way to get a toolchain</div>\n <div style=\"padding:13px 16px;font-family:'JetBrains Mono',monospace;font-size:12px;color:var(--lav)\">cargo --version</div>\n </div>\n <div style=\"display:grid;grid-template-columns:1.2fr 1.7fr 1.1fr\">\n <div style=\"padding:13px 16px;font-size:14.5px;font-weight:600\">A terminal</div>"),
]

# A SECOND "install detects the runtime" claim, on the Kiro CLI install page --
Expand Down
85 changes: 45 additions & 40 deletions tools/build-user-guide/sync-html-content.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@
"Both are owned by <code style=\"font-family:'JetBrains Mono',monospace;font-size:.87em;color:var(--tx)\">k-architect</code>, which carries 38 of the package's 82 skills — close to half, and by far the largest share of any agent."),
("reference roster note",
"k-architect is the only agent on a different model. Skill counts are from each spec's clientConfig.claudeCli.skills array.",
"Every agent runs claude-sonnet-5. Skill counts are from each spec's clientConfig.claudeCli.skills array, which matches dependencies.skills.skillNames everywhere except konductor — that one adds claude-teams-behavior for Claude Code only, so Kiro CLI sees 12.",),
"Every agent runs claude-sonnet-5.5. Skill counts are from each spec's clientConfig.claudeCli.skills array, which matches dependencies.skills.skillNames everywhere except konductor — that one adds claude-teams-behavior for Claude Code only, so Kiro CLI sees 12.",),
# ---- Claude Code does not prefix agent names ----------------------------
# Spent: the prefix sentences these edits produced have since been removed
# from the guide entirely, so neither their `old` nor their `new` exists any
Expand Down Expand Up @@ -229,10 +229,6 @@
# Nothing has been published to download, and the step already built from a
# clone -- the heading and the lead-in were the last two places still framing
# it as a fetch, one of them by narrating the absent release.
("qs prereq row: release framing",
">No release has been published yet, so you build the CLI from a clone — rustup is the "
"usual way to get one<",
">Built from a clone of the repository — rustup is the usual way to get a toolchain<"),
("qs step 1 heading", ">Download the CLI</h3>", ">Build the CLI</h3>"),
("qs step 1 toc", ">1 — Download the CLI</a>", ">1 — Build the CLI</a>"),
("qs step 1 intro", ">Get the build for your platform:</p>",
Expand Down Expand Up @@ -290,32 +286,32 @@
# `new` and move the previous `new` into `old`.
ROSTER = [
("ref konductor",
'{"k":"konductor","v":"claude-sonnet-5 · kiro-spec-workflow, k-delegate, k-plan, k-context-gathering, k-verify · 9 · —"}',
'{"k":"konductor","v":"claude-sonnet-5 · kiro-spec-workflow, k-delegate, k-plan, k-context-gathering, k-verify, k-light-ui-testing, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, about-konductor · 13 · —"}'),
'{"k":"konductor","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-delegate, k-plan, k-context-gathering, k-verify · 9 · —"}',
'{"k":"konductor","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-delegate, k-plan, k-context-gathering, k-verify, k-light-ui-testing, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, about-konductor · 13 · —"}'),
("ref mux",
'{"k":"konductor-mux-orchestrator","v":"claude-sonnet-5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify · 8 · —"}',
'{"k":"konductor-mux-orchestrator","v":"claude-sonnet-5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, k-light-ui-testing, about-konductor · 10 · —"}'),
'{"k":"konductor-mux-orchestrator","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify · 8 · —"}',
'{"k":"konductor-mux-orchestrator","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, k-light-ui-testing, about-konductor · 10 · —"}'),
("ref cmux",
'{"k":"konductor-cmux-orchestrator","v":"claude-sonnet-5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify · 8 · —"}',
'{"k":"konductor-cmux-orchestrator","v":"claude-sonnet-5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, k-light-ui-testing, about-konductor · 10 · —"}'),
'{"k":"konductor-cmux-orchestrator","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify · 8 · —"}',
'{"k":"konductor-cmux-orchestrator","v":"claude-sonnet-5.5 · kiro-spec-workflow, k-plan, k-context-gathering, k-verify, k-comprehensive-search, k-full-sdlc, k-e2e-test-generation, k-light-ui-testing, about-konductor · 10 · —"}'),
("ref architect",
'{"k":"k-architect","v":"claude-sonnet-5 · k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review · 37 · aws-mcp"}',
'{"k":"k-architect","v":"claude-sonnet-5 · k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review · 38 · aws-mcp"}'),
'{"k":"k-architect","v":"claude-sonnet-5.5 · k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review · 37 · aws-mcp"}',
'{"k":"k-architect","v":"claude-sonnet-5.5 · k-design-doc-creation, k-existing-design-review, k-principal-engineer-design-review, k-adversarial-pull-request-review · 38 · aws-mcp"}'),
("ref developer",
'{"k":"k-developer","v":"claude-sonnet-5 · k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow · 26 · aws-mcp"}',
'{"k":"k-developer","v":"claude-sonnet-5 · k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow · 27 · aws-mcp"}'),
'{"k":"k-developer","v":"claude-sonnet-5.5 · k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow · 26 · aws-mcp"}',
'{"k":"k-developer","v":"claude-sonnet-5.5 · k-code-cleanup, k-pre-cr-critique, k-codebase-analysis, k-code-review-workflow · 27 · aws-mcp"}'),
# k-code-review-workflow was removed from k-quality-assurance's spec as
# unusable (it spawns k-architect, which QA cannot reach), so QA is down to
# one declared SOP.
("ref qa",
'{"k":"k-quality-assurance","v":"claude-sonnet-5 · k-test-coverage-review, k-code-review-workflow · 11 · —"}',
'{"k":"k-quality-assurance","v":"claude-sonnet-5 · k-test-coverage-review · 12 · —"}'),
'{"k":"k-quality-assurance","v":"claude-sonnet-5.5 · k-test-coverage-review, k-code-review-workflow · 11 · —"}',
'{"k":"k-quality-assurance","v":"claude-sonnet-5.5 · k-test-coverage-review · 12 · —"}'),
("ref pm",
'{"k":"k-product-manager","v":"claude-sonnet-5 · none · 15 · —"}',
'{"k":"k-product-manager","v":"claude-sonnet-5 · none · 16 · —"}'),
'{"k":"k-product-manager","v":"claude-sonnet-5.5 · none · 15 · —"}',
'{"k":"k-product-manager","v":"claude-sonnet-5.5 · none · 16 · —"}'),
("ref researcher",
'{"k":"k-researcher","v":"claude-sonnet-5 · none · 7 · —"}',
'{"k":"k-researcher","v":"claude-sonnet-5 · none · 8 · —"}'),
'{"k":"k-researcher","v":"claude-sonnet-5.5 · none · 7 · —"}',
'{"k":"k-researcher","v":"claude-sonnet-5.5 · none · 8 · —"}'),
("sop owners: k-code-review-workflow",
'{"k":"k-code-review-workflow","v":"k-developer, k-quality-assurance · source_dir"}',
'{"k":"k-code-review-workflow","v":"k-developer · source_dir"}'),
Expand Down Expand Up @@ -362,26 +358,26 @@
'"rows":[{"k":"k-architect","v":"32"},{"k":"k-developer","v":"20"},{"k":"k-product-manager","v":"14"},{"k":"k-tpm","v":"14"},{"k":"konductor","v":"12"},{"k":"konductor-cmux-orchestrator","v":"11"},{"k":"konductor-mux-orchestrator","v":"11"},{"k":"k-quality-assurance","v":"10"},{"k":"k-researcher","v":"7"},{"k":"k-browser","v":"4"},{"k":"k-media-analyzer","v":"1"}]',
'"rows":[{"k":"k-architect","v":"38"},{"k":"k-developer","v":"27"},{"k":"k-product-manager","v":"16"},{"k":"k-tpm","v":"14"},{"k":"konductor","v":"13"},{"k":"k-quality-assurance","v":"12"},{"k":"konductor-cmux-orchestrator","v":"10"},{"k":"konductor-mux-orchestrator","v":"10"},{"k":"k-researcher","v":"8"},{"k":"k-browser","v":"4"},{"k":"k-media-analyzer","v":"1"}]'),
# at-a-glance cards
("card konductor", 'Coordinator. Delegates everything, implements nothing. claude-sonnet-5 · 9 skills · 5 SOPs',
'Coordinator. Delegates everything, implements nothing. claude-sonnet-5 · 13 skills · 10 SOPs'),
("card mux", 'Same, dispatching into tmux/zellij panes. claude-sonnet-5 · 8 skills · 4 SOPs',
'Same, dispatching into tmux/zellij panes. claude-sonnet-5 · 10 skills · 9 SOPs'),
("card cmux", 'Same, dispatching into cmux surfaces. claude-sonnet-5 · 8 skills · 4 SOPs',
'Same, dispatching into cmux surfaces. claude-sonnet-5 · 10 skills · 9 SOPs'),
("card pm", 'Requirements, user stories, decision research. claude-sonnet-5 · 15 skills · 0 SOPs',
'Requirements, user stories, decision research. claude-sonnet-5 · 16 skills · 0 SOPs'),
("card architect", 'System designs, APIs, data models, threat models. claude-sonnet-5 · 37 skills · 4 SOPs · aws-mcp',
'System designs, APIs, data models, threat models. claude-sonnet-5 · 38 skills · 4 SOPs · aws-mcp'),
("card developer", 'Implementation, code review, git, builds. claude-sonnet-5 · 26 skills · 4 SOPs · aws-mcp',
'Implementation, code review, git, builds. claude-sonnet-5 · 27 skills · 4 SOPs · aws-mcp'),
("card qa", 'Test coverage, E2E strategy, security tests. claude-sonnet-5 · 11 skills · 2 SOPs',
'Test coverage, E2E strategy, security tests. claude-sonnet-5 · 12 skills · 1 SOP'),
("card researcher", 'External documentation and web research. claude-sonnet-5 · 7 skills · 0 SOPs',
'External documentation and web research. claude-sonnet-5 · 8 skills · 0 SOPs'),
("card konductor", 'Coordinator. Delegates everything, implements nothing. claude-sonnet-5.5 · 9 skills · 5 SOPs',
'Coordinator. Delegates everything, implements nothing. claude-sonnet-5.5 · 13 skills · 10 SOPs'),
("card mux", 'Same, dispatching into tmux/zellij panes. claude-sonnet-5.5 · 8 skills · 4 SOPs',
'Same, dispatching into tmux/zellij panes. claude-sonnet-5.5 · 10 skills · 9 SOPs'),
("card cmux", 'Same, dispatching into cmux surfaces. claude-sonnet-5.5 · 8 skills · 4 SOPs',
'Same, dispatching into cmux surfaces. claude-sonnet-5.5 · 10 skills · 9 SOPs'),
("card pm", 'Requirements, user stories, decision research. claude-sonnet-5.5 · 15 skills · 0 SOPs',
'Requirements, user stories, decision research. claude-sonnet-5.5 · 16 skills · 0 SOPs'),
("card architect", 'System designs, APIs, data models, threat models. claude-sonnet-5.5 · 37 skills · 4 SOPs · aws-mcp',
'System designs, APIs, data models, threat models. claude-sonnet-5.5 · 38 skills · 4 SOPs · aws-mcp'),
("card developer", 'Implementation, code review, git, builds. claude-sonnet-5.5 · 26 skills · 4 SOPs · aws-mcp',
'Implementation, code review, git, builds. claude-sonnet-5.5 · 27 skills · 4 SOPs · aws-mcp'),
("card qa", 'Test coverage, E2E strategy, security tests. claude-sonnet-5.5 · 11 skills · 2 SOPs',
'Test coverage, E2E strategy, security tests. claude-sonnet-5.5 · 12 skills · 1 SOP'),
("card researcher", 'External documentation and web research. claude-sonnet-5.5 · 7 skills · 0 SOPs',
'External documentation and web research. claude-sonnet-5.5 · 8 skills · 0 SOPs'),
]


def apply_all(page, problems):
def apply_all(page, problems, edits=None):
"""Apply every edit exactly once, and never twice.

Whether an edit has already been applied cannot be decided the same way for
Expand All @@ -404,7 +400,7 @@ def apply_all(page, problems):
roster and card targets differ only by a little surrounding markup -- would
be silently rewritten too. Counting first turns that into a loud failure.
"""
for label, old, new in EDITS + ROSTER + SOP_EDITS:
for label, old, new in (EDITS + ROSTER + SOP_EDITS if edits is None else edits):
hits = page.count(old)
if hits > 1:
problems.append(f"{label} (matched {hits}x, expected 1)")
Expand Down Expand Up @@ -458,6 +454,15 @@ def main():
if new == page:
print(f" {rel}: no change")
continue
# Per-edit already-applied checks can't see two edits undoing each other.
if not problems and apply_all(new, []) != new:
failed = True
again = [e[0] for e in EDITS + ROSTER + SOP_EDITS if apply_all(new, [], [e]) != new]
print(f" {rel}: NOT written — a second pass would change the result again; "
f"edit(s) still firing:")
for label in again or ["(only in combination)"]:
print(f" - {label}")
continue
matched = len(EDITS) + len(ROSTER) + len(SOP_EDITS) - len(problems)
# Never write a partially-patched bundle. Without this guard an --apply
# run with unmatched targets still saved the subset that did match and
Expand All @@ -475,7 +480,7 @@ def main():
htmlbundle.save(bundle, new)

if failed:
print("\nSome edits did not match. The bundle has moved on -- update EDITS.",
print("\nSome edits did not match or are not idempotent -- update EDITS.",
file=sys.stderr)
return 1
if not args.apply:
Expand Down
Loading