fix(agentic-engineering): keep generated documentation to what a user needs

.claude-plugin/marketplace.json

@@ -20,7 +20,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md",
-      "version": "7.6.3",
+      "version": "7.6.4",
       "source": "./plugins/agentic-engineering"
     },
     {

.github/plugin/marketplace.json

@@ -20,7 +20,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md",
-      "version": "7.6.3",
+      "version": "7.6.4",
       "source": "./plugins/agentic-engineering"
     },
     {

plugins/agentic-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md",
-  "version": "7.6.3",
+  "version": "7.6.4",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md",
-  "version": "7.6.3",
+  "version": "7.6.4",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — `agentic-engineering`
 
+## 7.6.4 — 2026-11-11
+
+**Changed** — `write-readme` now says what the README of something people call (an action, a
+command, a script, a module or a template) holds: what it is for, one working example, what goes
+in and what comes out, and the constraints that change what a user does. Each requirement is
+stated once, where the reader first needs it. The full contract is linked, not copied. How it works
+inside, why it was built that way and how it was tested move to a design note, the contribution
+guide or the review, and safety and setup steps stay. `product-documentation` carries the same rule
+for user guides, and `product-engineering` for documentation written alongside a change (#687).
+
 ## 7.6.3 — 2026-11-11
 
 **Changed** — the `product-engineering` and `agent-improvement` descriptions are shorter (554 and

plugins/agentic-engineering/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md",
-  "version": "7.6.3",
+  "version": "7.6.4",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/skills/product-documentation/SKILL.md

@@ -46,7 +46,11 @@ skill is available. Choose concrete navigation labels from what users do or look
 Keep troubleshooting near the failing task: symptom, likely cause, a diagnostic
 step, a correction and the result that confirms recovery.
 
-Write direct instructions. Put prerequisites before commands and expected output
+Write direct instructions in plain words. Say each thing once, on the page where the
+reader needs it, and link to it from elsewhere. Keep implementation notes, design
+history and the author's own validation record out of tutorials, task guides and
+reference: explain a design on its own page when users need it, and leave the rest to
+code comments and the review. Put prerequisites before commands and expected output
 after them. Make placeholders unmistakable, keep secrets out of examples, state
 where commands run, and explain destructive or externally visible effects. For
 upgrades, preserve operator-owned values and distinguish workload rollback from

plugins/agentic-engineering/skills/product-engineering/SKILL.md

@@ -182,7 +182,9 @@ Docs are part of the product.
 
 - **Sync (definition of done).** A change that alters behaviour, flags, commands, config, or UX
   updates the affected docs **in the same PR** — re-running, never hand-editing, any doc generator.
-  If something merged without its docs, backfill in a focused `docs:` PR.
+  Add what a user of the change needs, once: what it does, an example, inputs and constraints.
+  Author-only notes and test results go in code comments and the PR. If something merged without
+  its docs, backfill in a focused `docs:` PR.
 - **Improve (on the docs Cadence).** Pick an under-served area and make it genuinely better: fix
   inaccuracies and stale examples, fill missing how-tos, tighten onboarding flow, repair dead links.
   Verify examples actually run. `docs:`-only PRs are real advance work, not filler.
@@ -191,10 +193,9 @@ Docs are part of the product.
   Architecture and reference guides retain details needed to understand, diagnose or change the
   system. Use short paragraphs, concise lists and tables where they make the page easier to scan.
 - **Improve READMEs without flattening them.** Preserve useful positioning, visuals, feature
-  summaries and support links. Keep relevant, truthful badges together near the top; they can be a
-  compact scorecard linked to their real results. Keep the first useful step short, link deeper
-  procedures, and keep author-only validation reports out of the front page. Use available README
-  and contribution-writing skills for those documents; do not impose one template on every repo.
+  summaries and support links. Keep relevant, truthful badges near the top. Keep the
+  first useful step short and link deeper procedures. Use available README and
+  contribution-writing skills for those documents; do not impose one template on every repo.
 - **Describe the as-is, never the journey.** Documentation, code comments, and resource descriptions
   state the current behaviour, architecture, constraints, and rationale directly. Do not narrate how
   they arrived there through prior states, migrations, before/after comparisons, or origin stories.

plugins/agentic-engineering/skills/write-readme/SKILL.md

@@ -68,10 +68,42 @@ page. Preserve licensing, security reporting, attribution and contributor obliga
 generated-file ownership and leave vendored docs and dated evidence alone. A portfolio audit must
 inventory and classify relevant READMEs; reviewing root files alone proves nothing about the rest.
 
+## Keep to what a user needs
+
+Something people call, such as an action, a command, a script, a module or a template, needs a
+README with four parts: what it is for, one working example, what goes in and what comes out, and
+the constraints that change what a user does. That is usually the whole page.
+
+- **Inputs and outputs.** One row each: name, purpose, whether it is required, default. Required
+  ones first. When it returns nothing, show what the user sees instead: each result and its
+  message, with what to do. Where the full contract lives in a file the reader can open, such
+  as the action definition, a schema or the command's help, link to it instead of copying its
+  rules.
+- **Constraints.** What must be true before it works, what it refuses, and what it changes or
+  costs. Give the consequence and what to do about it in a sentence or two.
+- **Say each thing once.** Put a requirement or rule where the reader first needs it, usually
+  beside the example, and link there from anywhere else. A sentence that restates a table row
+  is a repeat, and so are two tables that list the same cases. Before finishing, search the
+  page for each requirement and rule and remove the repeats.
+
+Leave out what only the authors need: how it works inside, why it was built that way, which edge
+cases it was hardened against and how it was tested. A paragraph earns its place when someone who
+never opens the source needs it to succeed or to avoid harm. Move the rest instead of deleting it:
+a design note or code comment for the mechanism, the contribution guide or a maintainer page for
+release and recovery procedures, the review for validation results. Link to each of those pages
+once.
+
+Safety and setup stay, even when they sound like internals: a step without which the example
+fails, a permission, a side effect, a cost, or a case where the tool would report success without
+having checked anything. Give the reader the consequence and the action, and leave the mechanism
+to the linked page.
+
 ## Check the result as a reader
 
 Compare the draft with the original: can readers still see what they get, useful visuals, status,
 first steps and support without hunting? Remove detail that does not help them choose or act.
+Read it once more for repeats and author-only detail: a requirement stated in two sections, an
+input rule restated in prose, an account of internals or of testing.
 Shorter is useful only when it remains clear and correct; a word count or heading checklist cannot
 prove readability.