docs(packages): unify README structure across cli, lint, parser, mcp#71
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 ofdocs-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:
Per-package consolidation on top of the structural change:
lint.tsso 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.Task,TaskMetadata,Policy,TaskFile,PickResult) in the same block, and document thepickBestTaskordering contract inline.Diffstat: +177 / −359 across the four READMEs (net −182 including the TASKS.md hunk that removes the closed task block).
Acceptance check
Install,Use,API,See also,License, plus the H1 tagline).../cli/,../lint/,../parser/,../mcp/) and to the root (../../README.md,../../spec.md,../../docs/user-stories/) all resolve in the working tree.npm run build— passes.npm test— 407/407 tests pass across cli (183), lint (43), mcp (103), parser (78).npm run lint—Checked 1 file(s), found 0 error(s).npx -y @tasks-md/lint TASKS.md—Checked 1 file(s), found 0 error(s).closes docs-package-readme-consistency
🤖 Written by an agent, not Fyodor. Ping me if this looks off.