| name | album-analysis |
| description | Produce a new album entry for the app. Use when asked to add, analyse, or create an album entry. |
Album Analysis
Produces a complete new album entry for the current app, not a standalone HTML file.
Leading word: entry — every run produces one finished data/<id>.json entry, validated end-to-end.
When the user asks for multiple albums in one request, fan the work out in
parallel using multiple sub-agents. Give each album to its own sub-agent
whenever feasible, then merge the results in the main agent and run one
shared validation pass after all album files are in place.
Deep Reference
Use REFERENCE.md for the repo output model, schema fields,
energy mapping guide, timeline guidance, index refresh rules, scaffolder
preference, and the quality checklist.
Workflow
Step 1 — Gather Metadata
Use:
- MusicBrainz for the canonical track list and durations
- Wikipedia for:
- release date / year
- label and producer(s)
- genre cues
- notable context and production notes
- the album cover thumbnail
Extract and record:
- Full track list (number, title, duration)
- Total runtime
- Year / label / producer(s)
- Primary genre string for the app card
- 2–4 sentences of album overview
Completion criterion: all metadata fields listed above are populated with
verifiable sources.
Step 2 — Resolve External Listening Links
When populating listening links for the album detail page, include platform URLs according to business rules.
Rules:
- Include valid Spotify and YouTube links where possible
- If Spotify is unavailable for the album, provide an audio streaming alternative
- If YouTube is unavailable for the album, provide a video streaming alternative
- Prefer official artist, label, or platform-hosted releases over user-uploaded mirrors
- Do not leave both audio and video listening paths unresolved
Completion criterion: at least one audio and one video listening link is
resolved and recorded.
Step 3 — Resolve Album Cover from Wikipedia
Search Wikipedia for the album page and prefer the page summary thumbnail or equivalent Wikimedia-hosted image.
Rules:
- Prefer a
upload.wikimedia.org thumbnail URL when available
- Add that URL to the album's
coverUrl field in data/<id>.json
- If no reliable Wikipedia cover is found, omit
coverUrl rather than inventing one
- Do not add binary image files to the repo unless the user explicitly asks for local assets
Completion criterion: coverUrl is populated with a verified Wikimedia URL,
or explicitly omitted.
Step 4 — Build the Analysis Data
Populate data/<id>.json using the schema and energy mapping in REFERENCE.md.
For each track, derive energy, tags, role, and events per the reference guidance.
Completion criterion: every track has all derived fields populated, every
timestamp uses M:SS or MM:SS format, and the JSON validates against
src/shared/schema.ts.
Step 5 — Refresh the App Index
Regenerate data/index.json after writing data/<id>.json, using the scaffolder or npm run build. See REFERENCE.md for the derived summary shape and scaffolder invocation.
Completion criterion: the new entry appears correctly on index.html after
regeneration.
Step 6 — Validate
Run:
npm run build
npm test
Then verify locally:
http://127.0.0.1:3000/index.html
http://127.0.0.1:3000/album.html?id=<id>
Completion criterion: npm run build and npm test both pass, and the
entry renders correctly on both pages. Every item on the quality checklist in
REFERENCE.md is satisfied.
Step 7 — Remove from Future Research
After the new album entry is committed, check docs/future-research.md and
remove the matching row if it is still listed. Match by artist and album title
against the table rows — do not rely on the row number. If the entry is not
found in the file, skip this step.
Completion criterion: the album no longer appears in
docs/future-research.md.