[theCodeDrift]

Closes #672

What

taskless agent <topic> now prints a long topic as an outline that fits one agent tool call: the purpose, the steps, and a ## Sections on request list at the end. Reference material is printed on its own with taskless agent <topic> --section <name>. --full prints the whole recipe.

• Mechanism (packages/cli/src/prompts/sections.ts, new):
  • Every ## heading is a section, named by its slug.
  • An author marks a section <!-- on-demand --> (on the line above its heading) to leave it out of the outline. The marker is stripped at load, and a misplaced marker throws.
  • Same-recipe cross-references are markdown links ([Quirks](#quirks)). The full text keeps them as links. The outline and section output rewrite a link to an unprinted section as "section quirks".
  • A recipe with no on-demand section prints exactly as before.
• Command (agent.ts):
  • New --section and --full flags.
  • An unknown section exits 1 and lists the topic's sections.
  • A second positional is still refused, and the error now points at --section.
  • A section fetch captures cli_agent with a section property and never carries the feedback invite.
  • taskless onboard and taskless update serve the same outline.
• @taskless/cli/prompts is unchanged: it still renders whole recipes, with the markers removed.
• Recipes: the 17 that were over budget are restructured (each topic version bumped):
  • The steps stay in the outline and link to the detail.
  • Moved into sections: quirk tables, worked examples, input schemas, engine reach lists, update ledger entries, CI templates.
  • route's step 4 now tells the agent to print the ast-grep-reach, vale-reach and legacy-linters sections before deciding.
• Skill: tells the agent to print a section a step names before acting on that step.
• OpenSpec: cli-agent gains the outline/section requirement. The change is archived in this PR, since it is a single-PR delivery.

Budget

test/recipe-sections.test.ts holds every topic's outline, and every section printed alone, to 8 KiB (8192 bytes).

• It measures the worst realistic case: a nightly's long invocation plus the fetch-time directive.
• For the surveyed topics the feedback invite counts toward the budget.
• It also checks that every ](#name) link and every agent X --section y citation resolves.

Before, at default output: create-vale-rule 68KB, update 36KB, report 25KB, create-sg-rule 24KB, route 21KB, and 12 more over 8KB. After, all are under 8KB. create-vale-rule's outline is about 5.4KB.

Open questions for review

1. report --section facts-schema is over budget (~14KB). It is one fenced %(INPUT_SCHEMA)s, and compact JSON would still be 8.3KB. The test carries it as the only explicit exemption, and fails if the exemption goes stale. Fitting it needs the schema served in parts, which I left for a follow-up.

2. onboard is tight. Its outline is 7.9KB with the default host-tools text. With a real hostTools list and a nightly invocation it can pass 8KB. The test measures default caller state only.

3. route's outline is also tight, at about 8.0KB.

4. A few redundant sentences were dropped while restructuring rather than moved, all restatements of nearby text. In onboard.md:

   • step 4's summary of what route decides
   • "This recipe reads it; it does not duplicate it."
   • a repeated "follow the ci recipe"

   In ci.md: the repeated full/diff bullets and the three outcomes. Everything else was moved, not deleted.

5. Possible follow-up: update --json could list the ledger section names the walk covers, so an agent would not have to match versions itself.

6. Diff size: about 3.6k insertions and 2.0k deletions. Most of it is recipe text moved between sections. A split would leave a layer whose budget test is red.

[theCodeDrift]

@claude /review

[github-actions]

Claude finished @theCodeDrift's task in 3m 10s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json held no prior inline threads, review summaries, or comments besides the trigger itself, so this is the first review of this PR; every finding below is [New].

Summary

This is a well-executed, mechanically sound feature. The core mechanism (packages/cli/src/prompts/sections.ts) is small, pure, and does exactly what the PR description claims: lift markers at load time, split rendered text on `## ` headings (skipping fenced blocks), and rewrite same-recipe links to unprinted sections as `section \`name\. recipes.ts's new getServedRecipe/getServedRecipeText/onDemandSections are additive and don't disturb the existing getRecipe/getRawRecipe/getRenderedRecipe render paths beyond the mechanical RecipeSource type threading. agent.ts's --section/--full wiring, the unknown-section/too-many-positionals error paths, and the init.ts/onboard.ts switch to getServedRecipeText all look correct. The OpenSpec requirement addition in openspec/specs/cli-agent/spec.md accurately describes the shipped behavior. The test suite (recipe-sections.test.ts plus the updated call sites in agent-extensions, onboard, reconcile-marker, report, feedback-recipes, legacy-ladder) is thorough — it enforces the 8 KiB budget on every outline and every standalone section, validates every #name link and --section citation resolves, and exercises the actual --section/--full/unknown-section CLI paths end to end.

Spot-checked route.md, onboard.md, and update.md for section/link consistency against the new mechanism (cross-references, on-demand markers sitting directly above headings, the route step 4 instruction to print ast-grep-reach/vale-reach/legacy-linters) — all consistent with the described design.

I posted three inline findings, all minor and non-blocking:

1. sections.ts:194 — the sectionSlug(title) === name check in renderOutline's table-of-contents formatting is dead/tautological: name is always derived from title via sectionSlug in splitSections, so the condition can never be false. The ternary's real behavior is driven only by title.includes("\")`. Not a functional bug (no current heading has a backtick), but the comment above it implies a divergence check that doesn't exist — worth simplifying.
2. sections.ts:67 — no uniqueness check on section slugs. Two headings that slugify to the same name would silently collide: an on-demand marker on one would mark both (since onDemand is just a Set<string>), and --section <name> would always resolve to whichever section appears first in the file. No current recipe triggers this, but given how strict this module already is about failing fast on malformed markers, a one-line duplicate check seems in the spirit of the design.
3. agent.ts:370 — passing --section and --full together silently prefers --section with no documentation of the precedence and no test for the combination.

The four "open questions for review" the author flagged in the PR body (the report --section facts-schema budget exemption, onboard/route's tight margins, and the dropped redundant sentences) are self-disclosed and already reflected faithfully in the code/tests (e.g. the OVER_BUDGET_SECTIONS exemption map in recipe-sections.test.ts that fails if it goes stale) — I didn't find anything beyond what's already called out there.

[theCodeDrift]

Re: @github-actions — "Claude finished @theCodeDrift's task in 3m 10s…"
#693 (comment)

All three inline findings are addressed in 99a7785 (tautological slug check removed, duplicate section names now throw, --section with --full rejected), with tests for each.

— AI Coding Agent

[theCodeDrift]

Rebased onto main after #682, #683, #685, #686, #687, #688, #689 and #691 landed. Conflicts and what the resolution did:

• Topic versions, set one above main: check v11, ci v12, create-runtime-rule v10, create-sg-rule v18, create-vale-rule v23, improve-rule (anonymous) v8, onboard v14, route v12, validate-rule v12. The onboard and route version assertions follow.
• check.md: feat(check): per-rule summary in check --json, --summary, and one finding schema shared with verify #688's summary field carried into the moved What runs section.
• create-sg-rule.md: docs(agent): show a scope exclusion with folder fixtures, and say so in the never-read error #687's scope-exclusion sentence went into the Fixtures section; fix(validate): state sg-regex-needs-kind in the ast-grep rule schema #682's "every regex at any depth needs a kind" text into Feedback loop; feat(cli): add taskless ast <file> to show a file's named-node AST #683's taskless ast guidance into a new on-demand Reading kinds section, with a pointer in step 4.
• onboard.md: feat(onboard): mine reviews across the whole window in busy repositories #685's "Count while you mine" paragraph went into Choosing candidates; fix(onboard): route defers its questions to the recipe that sent the agent #686's answers to route's questions into a new on-demand Questions route asks section that step 8 points to. Tests updated to read those sections.

A separate commit (docs(agent): fit recipes merged from main back into the section budget) brings three outputs back under 8 KiB after the merge:

• create-sg-rule outline: step 5 no longer lists the quirks one by one, since the Quirks table has them.
• pattern-quirks: the relational entries (follows/precedes, fix(validate): notice has/inside without stopBy, like follows/precedes #691's has/inside, not) moved to a new relational-quirks section, which validate-rule also names.
• route outline: fix(onboard): route defers its questions to the recipe that sent the agent #686's note on recipes that limit questions moved to an on-demand Limits on asking section, with a one-line pointer left in Preconditions. The in-place qualifiers at step 7, the clarifying question and the fallback stay.

— AI Coding Agent