Skip to content

feat(fusion-tsdoc-readme): add reusable TSDoc and README documentation skill#125

Draft
odinr wants to merge 1 commit intomainfrom
feat/tsdoc-readme-skill
Draft

feat(fusion-tsdoc-readme): add reusable TSDoc and README documentation skill#125
odinr wants to merge 1 commit intomainfrom
feat/tsdoc-readme-skill

Conversation

@odinr
Copy link
Collaborator

@odinr odinr commented Mar 23, 2026

Why

No reusable skill exists for systematic TSDoc and README documentation passes across packages. The workflow was proven effective across a 41-package documentation sprint on equinor/fusion-framework (equinor/fusion-core-tasks#599) but required bespoke prompts every time — no consistent quality bar, no orchestration guidance, and no review council.

Current behavior

  • TSDoc enforcement exists only as a sub-concern of fusion-code-conventions
  • No skill for running systematic documentation passes across multiple packages
  • No README structure standard or template for package documentation
  • Each documentation session reinvents what "good TSDoc" and "good README" look like

New behavior

New fusion-tsdoc-readme orchestrator skill with:

  • SKILL.md (180 lines) — repo-aware conventions discovery, TSDoc pass, README pass, review council, and multi-package orchestration workflow
  • agents/tsdoc.agent.md — scans exports, classifies documentation state, and improves TSDoc
  • agents/readme.agent.md — assesses README structure and rewrites to consistent format
  • agents/reviewer.agent.md — four-dimension review council (intent extraction, code comprehension, user-facing quality, retrieval fitness)
  • references/readme-structure.md — standard README section structure
  • references/orchestration.md — multi-package batching, context isolation, and token budget strategy
  • assets/readme-template.md — copy-pasteable README scaffold

Delegates TSDoc convention rules to fusion-code-conventions (declared in metadata.skills) rather than duplicating them.

References

  • Issue(s): Resolves equinor/fusion-core-tasks#702
  • Related PR(s): —
  • Docs / specs: Prior art from equinor/fusion-core-tasks#599 (41-package doc pass)

Reviewer focus

  • Start here (files/areas): skills/fusion-tsdoc-readme/SKILL.md
  • Verify these behavior changes: Skill appears in npx -y skills add . --list output, passes validate:skills and validate:ownership
  • Risky or security-sensitive parts: None — read-only documentation workflow skill, no scripts

Self review checklist

  • I scoped this PR to one clear purpose.
  • I followed CONTRIBUTING.md.
  • I did not include secrets, credentials, or sensitive data.
  • I reviewed my own diff for clarity and unintended changes.

…n skill

Orchestrator skill with three agents (tsdoc, readme, reviewer) for
systematic documentation passes across monorepo packages.

Includes:
- SKILL.md with repo-aware conventions discovery, TSDoc pass,
  README pass, review council, and multi-package orchestration
- tsdoc.agent.md for export scanning and TSDoc improvement
- readme.agent.md for README structure assessment and rewrite
- reviewer.agent.md for four-dimension quality review
- references/readme-structure.md for consistent README format
- references/orchestration.md for multi-package batching strategy
- assets/readme-template.md for package README scaffold

Resolves equinor/fusion-core-tasks#702
@github-actions
Copy link
Contributor

Changeset summary

Detected 1 changeset file(s):

.changeset/add-fusion-tsdoc-readme-skill.md:

---
"fusion-tsdoc-readme": minor
---

Add reusable skill for systematic TSDoc and README documentation passes

- Orchestrator SKILL.md with TSDoc pass, README pass, and review council workflow
- Three agents: tsdoc (export scanning and TSDoc improvement), readme (structure assessment and rewrite), reviewer (four-dimension quality review)
- References for README structure guide and multi-package orchestration strategy
- README template asset for consistent package documentation

Resolves equinor/fusion-core-tasks#702

@odinr odinr self-assigned this Mar 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant