docs: design repository cleanup and benchmark readme
This commit is contained in:
Umutcan Edizsalan
@@ -0,0 +1,125 @@
|
||||
# Repository Cleanup, README, and Benchmark Design
|
||||
|
||||
**Date:** 2026-07-17
|
||||
**Status:** Approved for implementation
|
||||
|
||||
## Objective
|
||||
|
||||
Prepare AutoCAD MCP Pro for a polished public release by removing local drafts
|
||||
and generated artifacts, replacing the oversized README with a concise English
|
||||
product narrative, and presenting reproducible benchmark evidence through a
|
||||
Python-generated chart that names relevant AutoCAD MCP alternatives.
|
||||
|
||||
The public presentation must be confident without declaring itself "the best."
|
||||
It should earn that impression through architecture, capabilities, tests,
|
||||
security controls, quality gates, and transparent benchmark methodology.
|
||||
|
||||
## Repository Cleanup
|
||||
|
||||
Delete private planning drafts and local/generated artifacts:
|
||||
|
||||
- Root drafts: `b.md` and `new.md` (and `p.md` only if it exists at implementation time).
|
||||
- Test and release output: `.codex-pytest-temp/`, `.pytest_cache/`,
|
||||
`.release-*/`, and `.tdd-*/`.
|
||||
- Tool and interpreter caches: `.ruff_cache/` and every `__pycache__/` directory.
|
||||
- Build and run output: `dist/`, `out/`, and `.coverage`.
|
||||
- Empty local tool state: `.firecrawl/` when it contains no user data.
|
||||
|
||||
Remove the draft-specific `b.md` and `new.md` entries from `.gitignore` after
|
||||
the files are deleted. Keep or add general ignore rules for reproducible cache,
|
||||
test, build, coverage, and generated CAD output so these directories do not
|
||||
reappear in Git status.
|
||||
|
||||
Preserve all product code and current version 1.3 work, including modified and
|
||||
untracked files in `backends/`, `engineering/`, `benchmarks/`, `tests/`, and the
|
||||
repository root. No product source file may be deleted merely because it is
|
||||
currently untracked.
|
||||
|
||||
## README Information Architecture
|
||||
|
||||
The README will be written in English and optimized for a new user evaluating
|
||||
and installing the server. It will be substantially shorter than the current
|
||||
document and use this order:
|
||||
|
||||
1. Hero: product name, one-sentence value proposition, essential badges, and a
|
||||
compact proof line.
|
||||
2. Quickstart: the shortest headless install/run path plus the live AutoCAD path.
|
||||
3. Benchmark evidence: generated chart, result interpretation, methodology
|
||||
boundary, and exact reproduction command.
|
||||
4. Differentiators: dual backends, deterministic CAD operations, closed-loop
|
||||
quality, and auditable delivery/security.
|
||||
5. Backend/capability comparison: make platform limitations explicit.
|
||||
6. MCP client configuration and environment variables.
|
||||
7. Tool discovery and representative workflows; avoid maintaining a fragile,
|
||||
exhaustive hardcoded catalog when runtime discovery is authoritative.
|
||||
8. Architecture and security model.
|
||||
9. Development, contributing, roadmap link or compact roadmap, author, and license.
|
||||
|
||||
Remove repeated claims, the long table of contents, inflated competitor language,
|
||||
and hardcoded counts that cannot be verified from the current source or test run.
|
||||
Retain the author's identity in a compact section rather than a long sales letter.
|
||||
|
||||
## Benchmark Visualization
|
||||
|
||||
Create a reproducible source-review benchmark presentation with three artifacts:
|
||||
|
||||
- `benchmarks/source_review.json`: dated, schema-versioned data containing the
|
||||
named projects, rubric totals or category values, evidence grade, source URL,
|
||||
and review boundary.
|
||||
- `benchmarks/render_chart.py`: deterministic Matplotlib renderer.
|
||||
- `docs/assets/autocad-mcp-benchmark.svg`: generated README asset.
|
||||
|
||||
The primary graphic will be a horizontal bar chart because it is readable on
|
||||
GitHub, supports long repository names, and makes score differences easier to
|
||||
compare than a radar chart. It will name at least:
|
||||
|
||||
- `U-C4N/Autocad-MCP`
|
||||
- `varavista/autocad-mcp`
|
||||
- `beiming183-cloud/AutoCAD-MCP`
|
||||
- `AnCode666/multiCAD-mcp`
|
||||
- `puran-water/autocad-mcp`
|
||||
- `NCO-1986/AutoCAD_mcp`
|
||||
|
||||
The chart must display the review date, the 100-point rubric context, and evidence
|
||||
quality. AutoCAD MCP Pro may receive a distinct accent color, but competitors
|
||||
must remain legible and must not be visually disparaged.
|
||||
|
||||
The README must clearly separate two evidence types:
|
||||
|
||||
1. The Python task runner's real AutoCAD MCP Pro result, currently a local
|
||||
ten-task self-check.
|
||||
2. The named cross-project source-review rubric used by the chart.
|
||||
|
||||
It must not imply that competitors ran the shared live task suite unless their
|
||||
adapters were actually executed. The chart subtitle or adjacent text will say
|
||||
that it is a source-reviewed capability benchmark rather than a shared live
|
||||
AutoCAD run. Scores and claims will be rechecked against current evidence before
|
||||
publication; stale values from the private draft will not be copied blindly.
|
||||
|
||||
The renderer should produce stable ordering and labels, use no network access,
|
||||
and fail with an actionable message when Matplotlib is unavailable. SVG is the
|
||||
canonical README format for sharp text at different display sizes.
|
||||
|
||||
## Verification
|
||||
|
||||
Implementation is complete only after these checks succeed:
|
||||
|
||||
- The intended generated/draft targets are absent and all resolved deletion
|
||||
targets were confined to the repository.
|
||||
- `git status` contains no cache, release, build, coverage, CAD-output, or draft
|
||||
noise; pre-existing product changes remain intact.
|
||||
- The chart regenerates from JSON using the documented Python command and the
|
||||
committed SVG matches the generated output.
|
||||
- README local links and referenced files resolve.
|
||||
- README capability, version, benchmark, and test claims match current code or
|
||||
fresh command output.
|
||||
- Ruff, the relevant benchmark tests, the full test suite, and package build are
|
||||
run in proportion to environment availability; any external limitation is
|
||||
reported explicitly rather than hidden.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
This work does not implement competitor runtime adapters, publish unexecuted
|
||||
live benchmark scores, redesign product APIs, or refactor version 1.3 product
|
||||
code. It only cleans the workspace, establishes honest benchmark presentation,
|
||||
and rebuilds the public README around verified evidence.
|
||||
Reference in New Issue
Block a user