docs: add claude/agents/skills guides with sole-author rule

AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+Tool-agnostic agent guidance for the ACE Music Studio repo. If you're driving Claude Code, Cursor, Aider, Codex, or anything else with file-edit + shell access, **start here**.
+
+This file is the authoritative project rulebook. `CLAUDE.md` is Claude-specific extensions; `SKILLS.md` is workflow rules. README.md is the public-facing project intro — different audience.
+
+---
+
+## TL;DR — the five rules
+
+1. **Mayank Gupta is sole author on every commit.** No agent co-author trailers. No "generated with…" footers. No `--author=` flag. Strip any tool-suggested attribution.
+2. **Backend = ACE-Step 1.5 XL SFT, not ComfyUI.** Don't add a ComfyUI dependency under any guise.
+3. **One pipeline instance for all modes.** Generate / Cover / Extend / Edit call different entry points on the same pipeline object. Don't instantiate per-mode — it doubles memory and breaks LoRA state.
+4. **Don't pin `spaces` in `requirements.txt`.** HF Spaces' ZeroGPU build injects its own version. A pin causes pip-resolve failure.
+5. **Locally is the source of truth.** All changes restart `python app.py` and verify on http://127.0.0.1:7860 BEFORE pushing to HF. The Space rebuild is ~5–10 min; iterate locally.
+
+If you can't satisfy these without changing architectural shape, **ask the user before proceeding**.
+
+---
+
+## Project shape
+
+Single-process Gradio 5.50 app, flat top-level Python layout.
+
+```
+app.py            Gradio Blocks entry + bootstrap + event handlers
+backend.py        AceMusicBackend; @spaces.GPU; duration_for; generate_with_retry
+modes.py          call_generate / call_cover / call_extend / call_edit (pure handlers)
+models.py         auto_device, MODEL_CONFIGS, vram_limit_for, HF symlink helper
+lora.py           safetensors header sniff + applied_lora context manager
+lyrics.py         Qwen 2.5 7B inference (MLX on Mac, transformers on CUDA)
+stems.py          Demucs htdemucs_ft stem separation wrapper
+postprocess.py    loudness normalisation + fade in/out
+ui.py             Five per-tab builders
+theme.py          Soft Dark Restraint palette + minimal CSS
+tooltips.py       Centralised info= strings — single source of truth
+tests/            L1+L2 tests + GPU-deselected smoke
+docs/superpowers/ spec + plan + brainstorm artifacts
+```
+
+Same code path locally (MPS / CUDA) and on HF Spaces. The only branching is whether `_bootstrap()` does the cache-mirror dance (Spaces) or just the symlink step (local).
+
+---
+
+## Locked architecture decisions
+
+These came out of brainstorming + spec design. Do not relitigate.
+
+| Decision | Why | Code reference |
+|---|---|---|
+| One `AceMusicBackend` instance, lazy init | Avoids ~60 s pipeline rebuild per request; LoRA revert is cleaner | `backend.get_backend` |
+| Mode dispatch = separate `call_*` functions | Clean handler boundaries; easy to test with mocked pipe | `modes.py` |
+| MPS `vram_limit = None` | `torch.mps` has no `mem_get_info`; any VRAM gate raises AttributeError otherwise | `models.vram_limit_for` |
+| `PYTORCH_ENABLE_MPS_FALLBACK=1` set at app import | A few MPS-unsupported ops crash mid-pipeline without it | `app.py` top-of-file |
+| HF cache → `./models/<repo>/` symlink at boot | ACE-Step's loader looks at local paths, NOT the HF cache snapshot layout | `app._bootstrap` |
+| MLX path for Qwen on Mac | mlx-lm is 3-4x faster than transformers on Apple Silicon for text inference | `lyrics.py` |
+| Stacked LoRA with safetensors sniff | 4 bundled presets + arbitrary uploads; header check avoids corrupt-file crashes | `lora.py` |
+
+---
+
+## Commit rules
+
+- **Conventional Commits:** `<type>(<scope>): <subject>`
+  - types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`
+- Subject is imperative, lowercase, **no trailing period**.
+- Body explains **why** when not obvious. Reference plan task IDs (Task 7, Task A, etc.) when the change implements a specific plan step.
+- Frequent small commits; one logical change per commit.
+- **No agent attribution** in commit message or body. See rule 1.
+- Don't `git push --force` to `main` unless the user explicitly says so.
+
+---
+
+## Verification rules
+
+- **Tests must pass before committing.** `python -m pytest tests/ -q` from the project root.
+- **Ruff must be clean.** `ruff check . && ruff format --check .`
+- **The local app must boot.** `python app.py` → http://127.0.0.1:7860 reachable, no import error in `/tmp/ace-music-studio.log`.
+- **For UI changes:** open the URL in a browser (or Playwright eval) and verify the change is rendered. Don't trust a clean test run + clean ruff as proof that the UI works.
+- **For deployment changes:** push to HF Space, watch the build, verify the runtime stage transitions to `RUNNING` before claiming success.
+
+If a change requires breaking these rules, write the reason in the commit body.
+
+---
+
+## Testing conventions
+
+- **TDD per the plan.** Failing test first, then implementation.
+- **L1 + L2 in CI** (no GPU). The mode handlers are tested with a mocked pipeline. We do NOT mock ACE-Step internals.
+- **L3 GPU smoke** is opt-in (`pytest -m gpu`). Lives in `tests/test_smoke_gpu.py`. Loads the real pipeline (~32 GB cache hit on a warm machine).
+- **L4 HF Space smoke** is manual. Push, wait, click each tab, verify audio renders.
+
+`pyproject.toml` has `addopts = -m 'not gpu'` so the default `pytest` invocation skips GPU. Add the marker before any test that touches ACE-Step weights.
+
+---
+
+## Out of scope (v1 cap — don't add without asking)
+
+Per spec §13. If you find yourself "while I'm here"-ing into one of them, stop.
+
+- Multi-prompt batch queue
+- Persistent generation history
+- User accounts
+- Telemetry dashboard
+- Voice cloning (RVC)
+- LoRA training in-app
+- ControlNet-style conditioning
+- Spectrogram visualization
+- Multi-language UI strings
+- Watermarking output audio
+- Browser audio editing
+- Multi-tenant rate limiting
+- DAW export
+
+If a feature you're adding requires one of these as a sub-step, **ask the user** before proceeding.
+
+---
+
+## When you're not sure
+
+1. Read `docs/superpowers/specs/2026-05-18-ace-music-studio-design.md` — that's the architectural source of truth.
+2. Read `docs/superpowers/plans/2026-05-18-ace-music-studio.md` — the task-by-task breakdown.
+3. Read `SKILLS.md` — process rules, debugging patterns, deployment workflow.
+4. `git log --oneline` — every non-obvious decision has a fix-commit explaining the reasoning.
+5. **Ask the user.** A clarifying question costs the user ten seconds. A wrong implementation costs everyone an hour.

CLAUDE.md

@@ -0,0 +1,127 @@
+# Project Guidelines — ACE Music Studio
+
+Working notes for AI assistants editing this repo. This file is the *what & why* — the locked architecture, the gotchas, the sole-author rule. Companion to `SKILLS.md` (the *how* — process, debugging, deployment workflow) and `AGENTS.md` (tool-agnostic version of this file).
+
+---
+
+## ⚠ Sole-author rule (non-negotiable)
+
+**Mayank Gupta is the sole author on every commit in this repo.** No exceptions.
+
+When committing:
+
+- **NO** `Co-Authored-By: Claude…` (or any agent name) trailer.
+- **NO** "Generated with Claude Code" / "🤖 Generated with…" footers.
+- **NO** `--author=…` flag — let git use the user's configured identity.
+- **NO** attribution in PR descriptions.
+
+If asked to amend, re-commit, or rebase, strip any prior agent attribution from the commit message. Treat any tooling that suggests adding a Claude trailer as a bug to ignore.
+
+---
+
+## Architecture facts (locked — do not relitigate)
+
+Spec: `docs/superpowers/specs/2026-05-18-ace-music-studio-design.md`
+Plan: `docs/superpowers/plans/2026-05-18-ace-music-studio.md`
+
+1. **Backend is ACE-Step 1.5 XL SFT** — not ComfyUI. Installed from git (the package isn't on PyPI). The upstream repo is `git+https://github.com/ace-step/ACE-Step-1.5.git`; the Apple Silicon fork is `git+https://github.com/clockworksquirrel/ace-step-apple-silicon.git`.
+2. **Five tabs.** Generate, Cover, Extend, Edit, Lyrics. Progressive disclosure — defaults stay short and reveal advanced controls only when asked.
+3. **One pipeline instance.** Single ACE-Step pipeline; mode handlers (generate / cover / extend / edit) call different pipeline entry points. No re-instantiation between calls.
+4. **`@spaces.GPU` is applied at module load time.** Identity decorator off Spaces. The decorator's `duration=` parameter takes a callable that estimates per-call timeout from `(mode, params, multiplier)`. Estimator clamps at `[60, 300] s`.
+5. **Qwen 2.5 7B handles lyrics generation.** Text-only inference; full multimodal weights are NOT required. On Mac the MLX path is used via mlx-lm.
+6. **HF cache → `./models/<repo>/` symlink.** ACE-Step looks for files at `local_model_path/...`. `app._bootstrap()` symlinks every cached snapshot into `./models/<org>/<repo>/` so the preload weights are findable. On Spaces, the build-user-owned `~/.cache/huggingface/hub` is mirrored to runtime-writable `~/hf-cache-rw/` first, then symlinked.
+7. **One Gradio process. Lazy backend singleton.** `get_backend()` constructs the pipeline on the first request (~30–60 s warm-up). Module import is fast.
+
+---
+
+## Gotchas we already paid for (don't re-discover)
+
+Each of these cost a debug cycle. Read once.
+
+### MPS / Apple Silicon
+
+- `torch.mps` has no `mem_get_info`. Any VRAM-gate that calls that method raises AttributeError. **Fix:** `vram_limit_for("mps")` returns `None` so the gate short-circuits.
+- Several ops aren't implemented on the MPS backend (SDPA variants, some index ops). `app.py` sets `PYTORCH_ENABLE_MPS_FALLBACK=1` so they degrade to CPU instead of crashing.
+
+### ACE-Step gotchas
+
+TBD as discovered during M1+ implementation. Record new ones here as they come up.
+
+### Dependency footguns
+
+- `ace-step` is NOT on PyPI. Install from git (see `requirements.txt`).
+- Don't pin `spaces` in `requirements.txt`. HF Spaces' ZeroGPU build injects its own version. A pin causes pip-resolve failure.
+- `transformers >= 5` may break imports. **Pin:** `transformers>=4.45,<5.0`.
+
+### Gradio 5 quirks
+
+- Don't put `<script>` tags inside `gr.HTML` blocks — they get stripped. JS goes in `gr.Blocks(head=…)`.
+- The Gradio 6.0 deprecation warnings about `theme=` / `css=` / `head=` on `Blocks` are benign on 5.50. Ignore until upgrade.
+
+### HF Spaces deployment
+
+- `preload_from_hub` is build-time only. Runtime falls back to network if any required file isn't preloaded. Use broad globs so configs + index.json files come along.
+- ZeroGPU build injects `spaces==0.50.0`. If `requirements.txt` pins `spaces==0.30.0`, pip resolution fails. **Don't pin `spaces` at all** — let HF provide it.
+- The `@spaces.GPU` decorator must be applied at module load. Runtime decoration isn't detected by ZeroGPU's startup analyzer.
+
+---
+
+## Coding conventions
+
+- **Python 3.11.** HF Spaces base image is 3.11; older syntax (like no `match`) is fine.
+- **Flat top-level layout.** No `src/`, no nested packages. One `.py` per responsibility.
+- **No conda.** `python3.11 -m venv .venv`; `brew` for system binaries.
+- **No emojis** in code or commits unless explicitly requested. UI strings (CTA banner, button labels) are OK because they're user-facing copy, not code.
+- **Type hints on public functions.** Internal helpers can skip them when obvious.
+- **Imports at the top of the file.** Inline imports only to break circular deps OR to defer heavy modules (ace-step, torch, mlx) for fast CI startup.
+- **`ruff format` + `ruff check`** both pass in CI. No exceptions.
+
+---
+
+## Commits
+
+- **Conventional Commits:** `<type>(<scope>): <subject>` — types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
+- Subject is **imperative**, lowercase, no trailing period.
+- Body explains **why** when not obvious. Reference the spec / plan section if relevant.
+- Frequent small commits — one logical change per commit.
+- **NO Claude trailer.** See top of file.
+
+---
+
+## Testing
+
+- **TDD per the plan.** Each implementation task has the failing test first.
+- **L1 + L2 in CI** (no GPU): module structure, mocked pipeline call boundaries, ruff. `tests/test_smoke_gpu.py` is the GPU smoke; it's marked with `@pytest.mark.gpu` and skipped by default (pyproject `addopts = -m 'not gpu'`).
+- **No mocks for ACE-Step internals.** Mock only the `pipe(...)` call boundary so the mode-handler logic is verified at the boundary.
+- **Use `pytest -m gpu`** to opt into the GPU smoke (~32 GB download on a cold cache; runs full generate + cover + extend + edit).
+
+---
+
+## Out of scope for v1 (don't add without asking)
+
+Per spec §13:
+
+- Multi-prompt batch queue
+- Persistent generation history
+- User accounts
+- Telemetry dashboard
+- Voice cloning (RVC)
+- LoRA training in-app
+- ControlNet-style conditioning
+- Spectrogram visualization
+- Multi-language UI strings
+- Watermarking output audio
+- Browser audio editing
+- Multi-tenant rate limiting
+- DAW export
+
+If a task feels like it needs one of these, stop and ask the user.
+
+---
+
+## When in doubt
+
+1. Read the spec + plan. Fifteen minutes of reading vs a day of wrong implementation.
+2. Read `SKILLS.md` for the process side — debugging, deployment, when to commit, when to verify.
+3. `git log --oneline` — most non-obvious decisions have a fix-commit explaining the reasoning.
+4. **Ask the user** before changing architectural shape or adding scope outside the v1 list.

SKILLS.md

@@ -0,0 +1,228 @@
+# SKILLS.md — how to work in this repo
+
+Process rules and habits for editing ACE Music Studio. Companion to `CLAUDE.md` (which is *what & why*); this file is *how* — debugging, verification, deployment, when to commit, when to ship.
+
+> **Default rule when in doubt:** stop and ask the user. The user prefers a question over wrong work.
+
+---
+
+## Investigation before fix
+
+### Reproduce the bug before patching
+
+When the user reports a layout, color, click, or visibility issue, **first action is verify, not code**. Open the local app (http://127.0.0.1:7860) in a browser OR via Playwright (`mcp__playwright__browser_*`) and reproduce the issue. Take a screenshot. THEN diagnose.
+
+Skipping the visual repro twice in a row will produce a patch that fixes a different symptom than the one the user is seeing.
+
+For shape / data bugs: read the stack trace fully, identify the line, then read the function — don't trust the line number alone.
+
+### Pull HF Space logs when something runs there
+
+For Spaces failures, the run logs are the source of truth.
+
+```bash
+HF_TOKEN=$(cat ~/.cache/huggingface/token)
+curl -s -H "Authorization: Bearer ${HF_TOKEN}" \
+  "https://huggingface.co/api/spaces/techfreakworm/ace-music-studio/logs/run" \
+  > /tmp/hf-runtime.log
+
+# Decode the SSE-style `data: {...}` lines
+python3 << 'PY'
+import json
+msgs = []
+for line in open('/tmp/hf-runtime.log'):
+    if line.startswith('data:'):
+        try: msgs.append(json.loads(line[5:].strip()).get('data', '').rstrip())
+        except Exception: pass
+with open('/tmp/hf-runtime-decoded.log', 'w') as f:
+    f.write('\n'.join(msgs))
+print(f'Decoded {len(msgs)} lines')
+PY
+
+tail -100 /tmp/hf-runtime-decoded.log
+```
+
+`/logs/run` is runtime container output. `/logs/build` is the image-build phase (pip install, preload, etc.). Different problems, different endpoints.
+
+### Stage check before action
+
+```bash
+curl -s https://huggingface.co/api/spaces/techfreakworm/ace-music-studio/runtime | python3 -m json.tool
+```
+
+Terminal stages: `RUNNING`, `RUNTIME_ERROR`, `BUILD_ERROR`. Transient: `BUILDING`, `APP_STARTING`, `RUNNING_BUILDING` (live serving while a new build runs). Always check `errorMessage` first when stage is non-RUNNING.
+
+### Sequential thinking for repeated failures
+
+The user has called this out: if a fix doesn't work on the first try, **stop patching**. Use the `superpowers:sequential-thinking` MCP and the `superpowers:systematic-debugging` skill. Two failed fixes is the signal — go back to root-cause investigation before attempting fix #3.
+
+Pattern that means you're guessing:
+- "Just try changing X and see if it works"
+- "I see another thing it could be — fix that too"
+- Multiple changes in one commit chasing a symptom
+
+Pattern that means you're investigating:
+- One hypothesis per cycle
+- Each hypothesis has a falsifying experiment
+- Experiments produce evidence before code changes
+
+---
+
+## Running locally
+
+```bash
+cd /Users/techfreakworm/Projects/llm/music-generator
+source .venv/bin/activate
+# Restart cleanly (kill anything on 7860)
+kill -9 $(lsof -ti:7860 2>/dev/null) 2>/dev/null || true
+sleep 1
+nohup .venv/bin/python app.py > /tmp/ace-music-studio.log 2>&1 &
+disown
+# Wait for ready
+for i in $(seq 1 30); do curl -sf http://127.0.0.1:7860/ -o /dev/null && echo "ready ${i}s" && break; sleep 1; done
+```
+
+`/tmp/ace-music-studio.log` is the live log. Tail it during development. The Monitor tool with a `grep -E "ERROR|Traceback|Exception"` filter is the right way to watch it across many turns without blowing context.
+
+LAN access for phone / tablet testing: `http://192.168.0.10:7860` (the LAN IP of the dev machine). Gradio binds to `0.0.0.0:7860` by default in `app.py`.
+
+---
+
+## Verification before committing
+
+Before every commit:
+
+1. **Tests pass.** `python -m pytest tests/ -q` → target 0 failures. New code adds new tests.
+2. **Ruff clean.** `ruff check . && ruff format --check .` — both no-op.
+3. **App boots.** Restart the local server (kill 7860, relaunch). Confirm "ready" within ~5 seconds and no traceback in `/tmp/ace-music-studio.log`.
+4. **The change is visible.** For UI changes, click through the affected tab in the browser. For backend changes, click Generate and verify the output matches expectation.
+
+Tests + ruff alone is not proof the UI works — the test suite mocks `pipe(...)` and doesn't exercise the Gradio render tree.
+
+---
+
+## When to commit
+
+- **One logical change per commit.** A fix and a refactor are TWO commits, not one.
+- After a test goes red → green, commit.
+- After fixing a regression, commit BEFORE adding the next feature.
+- Don't bundle "while I'm here" changes — they hide the actual fix in the diff.
+
+Conventional Commits format:
+
+```
+<type>(<scope>): <subject>
+
+<body — explains WHY, not what>
+```
+
+Types in use: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
+
+NO Claude trailer. NO "Generated with…" footer. See `CLAUDE.md` rule 1.
+
+---
+
+## Deployment workflow
+
+The repo has two remotes:
+
+```
+origin  → git@github.com:techfreakworm/ace-music-studio.git
+space   → https://huggingface.co/spaces/techfreakworm/ace-music-studio
+```
+
+To push:
+
+```bash
+git push origin main
+git push space main
+```
+
+After the `space` push, HF starts rebuilding. Watch:
+
+```bash
+TOKEN=$(cat ~/.cache/huggingface/token)
+while true; do
+  STATE=$(curl -s -H "Authorization: Bearer $TOKEN" \
+    https://huggingface.co/api/spaces/techfreakworm/ace-music-studio/runtime \
+    | python3 -c "import json,sys; print(json.load(sys.stdin).get('stage','?'))")
+  echo "$(date +%H:%M:%S) $STATE"
+  case "$STATE" in
+    RUNNING|BUILD_ERROR|RUNTIME_ERROR) break ;;
+  esac
+  sleep 30
+done
+```
+
+Typical build time: ~5 min after weights are cached. First build with new preload globs: ~15–20 min.
+
+### Don't push during HF testing
+
+When the user is actively testing on the live Space, hold local commits — don't push mid-test. They'll explicitly say "push it now" when they're ready.
+
+---
+
+## Adding a new model / weight
+
+1. Add a `ModelConfig(...)` entry to `models.MODEL_CONFIGS`.
+2. Add the file (or glob) to `preload_from_hub:` in `README.md`'s YAML frontmatter.
+3. Run tests, restart server, verify in browser, then commit.
+
+---
+
+## Adding a new mode / tab
+
+1. Spec the new mode in `docs/superpowers/specs/` first. Don't skip this.
+2. Add a `call_<mode>(pipe, params)` to `modes.py`. Same shape as the existing handlers.
+3. Add a `build_<mode>_tab()` to `ui.py`. Use the existing tabs as template.
+4. Wire `on_<mode>_generate()` in `app.py` with `progress=gr.Progress(track_tqdm=True)`. Connect `c["generate_btn"].click(...)`.
+5. Add tests in `tests/test_modes.py` mocking the `pipe` boundary.
+6. Update tooltips dict in `tooltips.py`.
+7. Update the spec + plan to reflect the new mode.
+
+---
+
+## When you have 2+ failed fixes
+
+This is a process signal, not a coding signal. Stop coding.
+
+1. Read `superpowers:systematic-debugging` (the Iron Law: no fixes without root-cause investigation).
+2. Use `mcp__sequential-thinking__sequentialthinking` to walk through hypotheses one at a time.
+3. Each hypothesis needs a falsifying experiment (a log line, a Playwright eval, a test). Run the experiment before writing code.
+4. If 3+ fixes have failed, the architecture is wrong — escalate to the user, don't attempt fix #4.
+
+This rule has saved several hours of thrashing in this repo. Honour it.
+
+---
+
+## Brainstorm + visual companion
+
+When making material UI changes, use:
+
+- `superpowers:brainstorming` to clarify what's actually being built
+- `superpowers:frontend-design` (or `frontend-design:frontend-design`) for design quality
+- The visual companion server (under `.superpowers/brainstorm/.../content/`) for mockups the user can click through
+
+The user's `.superpowers/` directory is git-ignored and persists per project. Don't prematurely re-mockup — confirm with the user that mockups are wanted before generating them.
+
+Default to RESTRAINT — single accent, single font, gradio-native shapes, progressive disclosure.
+
+---
+
+## Skills + sub-agents
+
+When dispatching subagents (Agent tool):
+
+- **Brief them like they walked in cold.** They see none of this conversation. Include file paths, line numbers, what to change, what NOT to change.
+- **Don't make a subagent read the plan file.** Paste the relevant section into the prompt.
+- **Use Opus for design + heavy refactors.** Sonnet for mechanical implementation. Haiku for trivial CSS / config changes.
+- **One subagent per task.** Two parallel subagents touching the same file is a guaranteed merge conflict.
+- **Subagents commit but don't push.** The user pushes when they've reviewed the diff locally.
+
+---
+
+## When in doubt
+
+1. Re-read the spec at `docs/superpowers/specs/2026-05-18-ace-music-studio-design.md`.
+2. `git log --oneline` — every non-obvious decision has a fix-commit explaining the reasoning.
+3. Ask the user. They prefer answering a clarifying question to debugging wrong code an hour later.