134 lines
7.0 KiB
Markdown
134 lines
7.0 KiB
Markdown
# Step 1: Project foundation and compatibility evidence inventory
|
|
|
|
## Objective
|
|
|
|
Implement only Step 1 of the approved `prompts/plan.md`: a reproducible Python
|
|
package foundation, working validation commands, and an honest inventory of the
|
|
evidence required for the target instruments and proprietary formats.
|
|
|
|
Read the approved plan and applicable repository instructions before editing.
|
|
Do not create another worker prompt, start a later step, or modify the plan's
|
|
scope. Preserve unrelated work. Do not commit.
|
|
|
|
## Files to create
|
|
|
|
- `pyproject.toml`
|
|
- `.gitignore`
|
|
- `README.md`
|
|
- `src/riff_groove_builder/__init__.py`
|
|
- `tests/unit/test_package.py`
|
|
- `tests/integration/test_distribution.py`
|
|
- `docs/architecture.md`
|
|
- `docs/compatibility.md`
|
|
- `docs/formats/agp.md`
|
|
- `docs/formats/sdp.md`
|
|
- `prompts/report_1.md`
|
|
|
|
Create another small support file only if needed for a working package or the
|
|
listed tests, and explain the reason in the report.
|
|
|
|
## Implementation details
|
|
|
|
1. Use the `src` package layout and a standard build backend. Set the project
|
|
name to `gaj3t-musicgen-riff-groove-builder` and the Python import package to
|
|
`riff_groove_builder`. An initial version of `0.1.0` is appropriate.
|
|
2. Confirm which Python interpreter is actually available. Adopt the proposed
|
|
Python >=3.11 policy only if the selected dependencies support it; record the
|
|
interpreter/version actually tested, without claiming untested runtimes.
|
|
3. Declare runtime dependencies on the official Python `mcp` SDK, Pydantic, and
|
|
Mido. Declare development/test dependencies for MIDIUtil, pytest, the SDK's
|
|
appropriate asynchronous testing support, Ruff, one type checker, and build
|
|
tooling. Use tested compatible ranges; do not guess nonexistent versions.
|
|
Do not add an audio backend, model-provider SDK, HTTP application, database,
|
|
plugin host, or general-purpose framework.
|
|
4. Keep the package initializer small. Publish a version using one authoritative
|
|
source so package metadata and the imported version agree.
|
|
5. Configure discoverable unit/integration tests, Ruff, and the chosen type
|
|
checker in `pyproject.toml`. Include package-data rules suitable for the future
|
|
profile JSON directory, without inventing profile files.
|
|
6. Use a repository-local virtual environment for installs if dependencies are
|
|
missing. Change the manifest before installing. Do not install into or modify
|
|
another user's/global environment. Ignore the environment and build/test
|
|
caches. Preserve normal source, prompts, and evidence documentation.
|
|
7. Document executable Windows-friendly commands for editable installation with
|
|
development dependencies, unit/integration tests, lint, types, and building
|
|
both wheel and sdist. Do not document an operational server command as working
|
|
before Step 3 implements it.
|
|
8. Write a concise architecture overview consistent with the approved plan.
|
|
The plan remains authoritative; avoid copying its entire contents.
|
|
9. Create a compatibility/evidence matrix with separate columns for MIDI
|
|
mappings, native layouts, automated checks, and application import acceptance.
|
|
Mark every currently unverified product/version/mapping honestly.
|
|
10. Document the native evidence requirements for each format: exact product and
|
|
version, real export/import workflow, lawful empty/one-note/multi-note files,
|
|
controlled tempo/velocity/articulation changes, and real load/save acceptance.
|
|
Distinguish evidence inventory completion from native-format completion.
|
|
11. Explain explicitly that a renamed MIDI file is not `.agp`/`.sdp` support, that
|
|
a preset-only container might not carry the requested musical content, and
|
|
that exact Eclips/Ray product names and versions still require confirmation.
|
|
Do not fabricate layouts, mappings, fixtures, or compatibility claims.
|
|
12. Use only publicly accessible official documentation for any external checks.
|
|
Do not upload private content, bypass login, copy licensed manuals, or add
|
|
native fixtures without redistribution permission.
|
|
|
|
## Required unit tests
|
|
|
|
- Importing the package succeeds.
|
|
- The public version is a nonempty valid release version and agrees with
|
|
installed distribution metadata.
|
|
- Importing the package does not emit stdout or start a server.
|
|
|
|
## Required integration tests
|
|
|
|
- Build an sdist and wheel successfully.
|
|
- Test the wheel in an isolated environment (a separate temporary venv is
|
|
appropriate), importing from a working directory outside the repository.
|
|
- Verify the installed package's version/metadata agreement in that environment.
|
|
- Ensure the distribution test does not pass by accidentally importing the
|
|
editable checkout or relying on the current working directory.
|
|
- A focused import-only wheel install may use `--no-deps` because Step 1's
|
|
initializer must not require the future server dependencies to import;
|
|
document that this is a package-layout test, not full dependency certification.
|
|
- The ordinary development environment must nevertheless resolve/install the
|
|
declared runtime and development dependencies and run the configured checks.
|
|
|
|
Make integration tests repeatable and offline once build dependencies are
|
|
installed. Do not force network access during every test run. Do not check in
|
|
build products or virtual environments.
|
|
|
|
## Validation and acceptance
|
|
|
|
Run the smallest relevant test selection, the configured lint and type checks,
|
|
and a real package build. Prefer the test tool when it can discover this project;
|
|
otherwise use the project's pytest command and record the exact invocation.
|
|
Fix failures caused by this step. List every skip, warning, and unresolved
|
|
environment limitation; do not replace failed checks with claims of success.
|
|
|
|
Acceptance requires:
|
|
|
|
- A working package, import-safe initializer, and independently installed wheel.
|
|
- Reproducible commands and passing Step 1 tests/lint/types/build.
|
|
- A truthful evidence inventory with unresolved native/mapping gates named.
|
|
- No production server, MIDI generator, native serializer, or fabricated profile
|
|
added prematurely.
|
|
|
|
Missing proprietary evidence is not a Step 1 implementation failure when it is
|
|
clearly documented, but it remains a blocker for the later corresponding steps.
|
|
|
|
## Required end-of-step report
|
|
|
|
When complete, write your end-of-step report to ./prompts/report_1.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
|
|
|
|
Place the entire report inside exactly one plain triple-backtick fence, with no
|
|
content outside it. Include:
|
|
|
|
- Files created/modified and the implementation summary.
|
|
- Exact interpreter and dependency versions actually tested.
|
|
- Exact validation commands with pass/fail counts and important output.
|
|
- Package-build and outside-checkout wheel-import evidence.
|
|
- Skipped checks or limitations and unresolved product/native/mapping evidence.
|
|
- A clear Step 2 readiness conclusion; do not claim full project readiness.
|
|
|
|
Do not silently stop after writing code: run validation, write the persistent
|
|
report, and return its location with a concise outcome.
|