Skip to content

docs(packages): unify README structure across cli, lint, parser, mcp#71

Merged
fyodoriv merged 1 commit into
mainfrom
docs/package-readme-consistency
May 3, 2026
Merged

docs(packages): unify README structure across cli, lint, parser, mcp#71
fyodoriv merged 1 commit into
mainfrom
docs/package-readme-consistency

Conversation

@fyodoriv
Copy link
Copy Markdown
Collaborator

@fyodoriv fyodoriv commented May 3, 2026

Why needed

The four published packages (cli, lint, parser, mcp) had drifted into different README shapes — different H2 sets, different ordering, different tone — so a reader who clones the repo had to re-orient inside every package directory before they could find Install vs. flags vs. API. The acceptance criteria of docs-package-readme-consistency (the P1 task this PR closes) calls for a single canonical structure across all four READMEs.

What changed

All four package READMEs now share the same H1 + five H2 blocks in the same order:

# <package-name>
## Install
## Use            -- the canonical use case in 5–10 lines
## API            -- CLI flags (cli, lint) or TS types (parser, mcp tools)
## See also       -- spec, root README, sibling packages
## License

Per-package consolidation on top of the structural change:

  • cli — collapse the 12 command sub-sections into one API table with flag references; pull the Jira / Linear / GitHub priority-mapping paragraphs into a single line that points at story 06 for the full walkthrough.
  • lint — re-derive the validation-rule table from lint.ts so it now also lists the **Blocked** / **Research** / **Last-enriched** rules that already shipped but were missing from the table; merge Usage + CI Integration + Example Output into Use + API.
  • parser — surface every exported helper in the API code-fence, list every interface (Task, TaskMetadata, Policy, TaskFile, PickResult) in the same block, and document the pickBestTask ordering contract inline.
  • mcp — tighten the tools table so each row is self-describing, fold Setup + Build from source into Use, drop the prose How-it-works bullets that duplicated the table.

Diffstat: +177 / −359 across the four READMEs (net −182 including the TASKS.md hunk that removes the closed task block).

Acceptance check

  • All four READMEs share the same five top-level headings (Install, Use, API, See also, License, plus the H1 tagline).
  • Cross-links between packages (../cli/, ../lint/, ../parser/, ../mcp/) and to the root (../../README.md, ../../spec.md, ../../docs/user-stories/) all resolve in the working tree.
  • Net diff is negative (−154 lines just on the four READMEs; consolidation, not addition).
  • npm run build — passes.
  • npm test — 407/407 tests pass across cli (183), lint (43), mcp (103), parser (78).
  • npm run lintChecked 1 file(s), found 0 error(s).
  • npx -y @tasks-md/lint TASKS.mdChecked 1 file(s), found 0 error(s).

closes docs-package-readme-consistency


🤖 Written by an agent, not Fyodor. Ping me if this looks off.

The four published packages (cli, lint, parser, mcp) had drifted into
different README shapes. Unify all four under the same five top-level
headings — `# <package-name>` (1-line tagline), `## Install`, `## Use`
(canonical use case), `## API` (CLI flags or TS types), `## See also`
(spec, root README, sibling packages), `## License` — so a reader who
clones the repo can scan any package the same way.

Other consolidation:

- cli: collapse the 12 command sub-sections into one API table with
  flag references; pull the Jira / Linear / GitHub priority mapping
  paragraphs into a single line that points at story 06 for the full
  walkthrough.
- lint: re-derive the validation-rule table from `lint.ts` so it now
  also lists the `**Blocked**` / `**Research**` / `**Last-enriched**`
  rules that already shipped but were missing from the table; merge
  Usage + CI Integration + Example Output into Use + API.
- parser: surface every exported helper in the API code-fence, list
  every interface (`Task`, `TaskMetadata`, `Policy`, `TaskFile`,
  `PickResult`) in the same block, and document the `pickBestTask`
  ordering contract inline.
- mcp: tighten the tools table so each row is self-describing, fold
  Setup + Build from source into Use, and remove the prose How-it-works
  bullets that duplicated the table.

Net diff: -154 lines across the four READMEs; every cross-link
between packages and to the root resolves; `npm run build`, `npm test`,
`npm run lint`, `npx -y @tasks-md/lint TASKS.md` pass.

closes docs-package-readme-consistency
@fyodoriv fyodoriv merged commit ef4baf4 into main May 3, 2026
4 checks passed
@fyodoriv fyodoriv deleted the docs/package-readme-consistency branch May 3, 2026 17:35
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