docs: add phase1-plan.md (org routing layer)#5
Merged
Merged
Conversation
Implementation plan for Phase 1 — generated tools.json, hand-curated task_index.json, strict llmstxt.org form, CI-gated. Mirrors phase0-plan.md's structure (Track Layout / Stage Matrix / Calling Convention / Risk Notes / Done Definition) so any agent can pick up a track or sub-stage by name and execute it. Four tracks, all in .github: - Track A (foundation) — tighten tools.schema.json, add task_index.schema.json, extract task_index.json, slim tools.json to summary shape. - Track B (after A) — TDD build-catalog.py + validate-catalog.py. - Track C (parallel) — rewrite llms.txt to strict llmstxt.org form. - Track D (after B and C) — Makefile targets + CI workflow step. Parent plan: AI-discoverability-plan.md §7. Phase 0 completion is the precondition: Phase 0 closed today with 3/3 tier-1 smoke green + docs-prose CI gate landed in all four repos.
rafael5
added a commit
that referenced
this pull request
May 11, 2026
…#20) Phase 3 Track A — recipe schema and directory scaffold. Foundation for Phase 3 Tracks B/C/D (B authors recipes; C TDDs the handshake test; D wires Make + CI). Per phase3-plan.md §2. Four parts in one coherent PR: 1. profile/recipe.schema.json (new) — JSON Schema 2020-12 for the YAML frontmatter at the top of every docs/recipes/<slug>.md. Required: id (typedID, recipe:* prefix), title (≤70 char), intent (matches a task_index entry), touches (≥1 typedID), verified_on (ISO date), ci_verifiable (bool). Optional: prereqs, manual_checklist_url, tier (tier-1|2|3), notes. allOf rule: ci_verifiable=false REQUIRES manual_checklist_url. typedID grammar duplicated in $defs so the schema validates standalone — same regex as tools.schema.json + task_index.schema.json. 2. docs/recipes/README.md (new) — describes the recipe contract, frontmatter table, the seven priority recipes (gating/buffer/ post-exit), the CI gate that Track D will implement, authoring guide, and what the directory is NOT. ~95 lines of prose. 3. profile/task_index.json — new top-level "recipes" category with one row per priority recipe mapping intent → recipe:<slug> typed ID + see_also pointers to the tools / cmds / modules each recipe touches. 7 rows. Total intent count 59 → 66. 4. (audit-only) A1 findings captured in this PR body — no existing recipe content anywhere in the org; only references in planning prose, and one adjacent surface (tools.json workflow block: tdd_inner_loop + minimal_application_recipe) that recipes do not replace. Verification, all green: - recipe.schema.json valid JSON Schema 2020-12; synthetic positive + two negative fixtures (missing manual_checklist_url when ci_verifiable=false; malformed typedID) both rejected as expected. - task_index.json validates against task_index.schema.json (now 6 categories, 66 intents). - profile/tools.json + task_index.json schema-strict via validate-catalog.py: OK. - make catalog byte-idempotent. - pytest profile/build/: 26/26. - make check-docs-prose green (docs/recipes/README.md is .md). - make phase0-smoke: PASS. Phase 3 launch state: - Track A this PR — foundation for everything else. - Tracks B/C/D ready to start in parallel once this lands. - recipes 1–4 are gating for Phase-3 exit (Track B); #5 is buffer; #6 (tier-2) + #7 (tier-3) are post-exit follow-ups.
rafael5
added a commit
that referenced
this pull request
May 11, 2026
) Track D §5 D3 + D4. Onboards the new tier-3 repo m-dev-tools-mcp into the org catalog and adds an agent_integration intent so "point my MCP-capable agent at the m-dev-tools catalog" routes to tool:m-dev-tools-mcp. Source-of-truth lives in m-dev-tools-mcp's dist/repo.meta.json (its phase4-D PR #5 renamed exposes.tools → exposes.mcp_tools and added exposes.release_wheel pointing at the v0.1.0 release asset). The new TIER_3 entry here is the org-side pickup: build-catalog.py fetches that repo.meta.json and translates each exposes.<kind> into <kind>_url, so the generated entry naturally carries: * repo_meta_url — the TIER_3 URL itself * mcp_tools_url — points at dist/mcp-tools.json (the 3-tool manifest) * release_wheel_url — absolute URL of v0.1.0 wheel asset * consumes / consumed_by — m-dev-tools-mcp consumes m-cli + m-stdlib + m-standard; inverse edges land on those entries No hand-edits to tools.json — `make catalog` byte-idempotent (regen-twice diff is empty). Preserves the "facts in repos, routing in meta-repo" architectural inversion. * profile/build/build-catalog.py: TIER_3 gains the m-dev-tools-mcp URL; comment bumped "nine onboarded repos" → "ten". * profile/task_index.json: new infra.agent_integration intent with doc URL pointing at the MCP server's examples/claude-code/README.md. Schema accepts the addition without bump (additive change, per schema-changelog discipline). * profile/llms.txt: new "Agent integration" section pointing at the m-dev-tools-mcp AGENTS.md. 26 → 30 lines (under the 40-line cap per parent plan §4.6). * profile/tools.json: regenerated. New tools.m-dev-tools-mcp entry with the URL-pointer fields; consumed_by inverse edges added to tools.m-cli / tools.m-stdlib / tools.m-standard. Verified locally: * make catalog → byte-identical on regen * make validate-catalog → OK * make phase0-smoke → PASS (no new tier-1 entries) * make recipes-check → 4/4 clean * make handshake → 8/8 steps green The v0.1.0 GitHub Release (https://github.com/m-dev-tools/m-dev-tools-mcp/releases/tag/v0.1.0) was cut from m-dev-tools-mcp main at 1ae96c4 before this PR; the wheel asset is the one release_wheel_url points at.
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
1 participant
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.
Summary
Implementation plan for Phase 1 — org routing layer. Mirrors
phase0-plan.md's structure (Track Layout · Stage Matrix · Calling Convention · Risk Notes · Done Definition) so any agent can pick up a track or sub-stage by name (`run A`, `run B3`, `run B+C in parallel`) and execute it.Track layout (sequence / priority / dependencies)
Recommended single-threaded order: A → (B in parallel with C) → D.
If only partial work can ship: prioritize A + D-minus-CI — that gets `task_index.json` split out and the schemas tightened, which is the largest single source of catalog drift. Phase 1 then becomes "ship the generator" rather than "ship the entire routing layer," and partial value lands sooner.
Phase 1 exit criterion
`make catalog && make validate-catalog` in `.github` is green; `tools.json` no longer contains hand-maintained subcommand / module / rule lists — they're pulled from each tier-1 repo's `dist/repo.meta.json` and its `exposes.*` payloads at build time.
Parent
`AI-discoverability-plan.md` §7 Phase 1.
Precondition
Phase 0 closed today — `make phase0-smoke` 3/3 PASS on `main`; tier-1 `docs/` cleaned to prose-only; CI gates landed.
Test plan