docs(specs): bootstrap Agent-OS-style spec + roadmap flow

[LucasSantana-Dev]

Summary

Introduces a lightweight spec + roadmap flow:

• docs/specs/<date>-<slug>/spec.md + tasks.md per feature with YAML frontmatter (status, created, owner, pr, tags).
• docs/roadmap.md auto-generated by ~/.claude/rag-index/specs.py roadmap --repo ..
• Shipped specs archive under docs/specs/archived/ via spec-ship.

Seeded

• 2026-04-15-internal-notify-endpoint (shipped via feat(backend): /api/internal/notify endpoint (homelab notifications) #625, archived with PR link).
• 2026-04-15-autoplay-diversity (proposed).

Risk

None. Docs only. No runtime impact.

Summary by CodeRabbit

• Documentation
  • Added a public roadmap outlining upcoming features and recently shipped improvements, with detailed specifications and implementation tracking.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lucky	Ready	Preview, Comment	Apr 15, 2026 7:17pm

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces documentation for project tracking and feature specifications. It adds an auto-regenerated roadmap, a proposed "autoplay-diversity" feature specification with task checklist, and an archived "internal-notify-endpoint" specification documenting a completed internal notification endpoint for homelab alerts.

Changes

Cohort / File(s)	Summary
Roadmap and Index docs/roadmap.md	Auto-regenerated roadmap tracking proposed and recently shipped features with tags and PR references.
Autoplay Diversity Specification docs/specs/2026-04-15-autoplay-diversity/spec.md, docs/specs/2026-04-15-autoplay-diversity/tasks.md	Feature specification for auto-queued song results with multi-objective ranking (similarity, artist/album dedup penalties, audio features boost) and task checklist with six pending work items including evaluation harness and production soak period.
Archived Internal Notify Endpoint docs/specs/archived/2026-04-15-internal-notify-endpoint/spec.md, docs/specs/archived/2026-04-15-internal-notify-endpoint/tasks.md	Completed specification for a bot-token-backed REST proxy endpoint (POST /api/internal/notify) to replace Discord webhooks, with six completed task items and Supertest coverage verification.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(bot): improve autoplay with spotify-first search and smarter scoring #493: Implements autoplay queue replenishment logic with candidate filtering, duration penalties, and recommendation scoring that directly aligns with the autoplay-diversity specification's multi-objective ranking approach.
• fix(autoplay): reject long tracks, boost Spotify, strip tribute/duration noise #594: Implements concrete autoplay scoring changes (long-track rejection, quality penalties, artist boost adjustments) that correspond to the specification's deduplication and feature-matching penalties.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a specification and roadmap workflow with example seed specs. It's concise, specific, and clearly communicates the primary purpose of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/specs-bootstrap

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/roadmap.md (1)

1-4: Consider adding an explicit “do not edit manually” guard.

Since this file is generated, a short note like “Generated file — edit specs, not this file” can prevent accidental manual drift.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/roadmap.md` around lines 1 - 4, Add a short explicit "Generated file —
do not edit manually; edit specs instead" guard at the top of docs/roadmap.md
(immediately under the title or as a top-of-file comment) so readers know the
file is auto-regenerated; update the heading block or insert a one-line
comment/banner that includes the generation timestamp phrase (e.g.,
"Auto-regenerated 2026-04-15 from `docs/specs/`") and a clear instruction to
edit specs, not this file, to prevent manual edits.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/roadmap.md`:
- Around line 1-4: Add a short explicit "Generated file — do not edit manually;
edit specs instead" guard at the top of docs/roadmap.md (immediately under the
title or as a top-of-file comment) so readers know the file is auto-regenerated;
update the heading block or insert a one-line comment/banner that includes the
generation timestamp phrase (e.g., "Auto-regenerated 2026-04-15 from
`docs/specs/`") and a clear instruction to edit specs, not this file, to prevent
manual edits.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b1bee69b-8111-4b3b-b1ba-dea30434512a

📥 Commits

Reviewing files that changed from the base of the PR and between cd092f2 and b8730ad.

📒 Files selected for processing (5)

• docs/roadmap.md
• docs/specs/2026-04-15-autoplay-diversity/spec.md
• docs/specs/2026-04-15-autoplay-diversity/tasks.md
• docs/specs/archived/2026-04-15-internal-notify-endpoint/spec.md
• docs/specs/archived/2026-04-15-internal-notify-endpoint/tasks.md

📜 Review details

🧰 Additional context used

🪛 LanguageTool

docs/specs/archived/2026-04-15-internal-notify-endpoint/tasks.md

[grammar] ~4-~4: Ensure spelling is correct
Context: ...x] Draft route + frontmatter - [x] Wire setupInternalNotifyRoutes - [x] Supertest coverage - [x] docker-c...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (4)

docs/specs/2026-04-15-autoplay-diversity/tasks.md (1)

1-8: Clear and execution-ready task checklist.

The checklist is concise and maps cleanly to the proposed implementation and rollout steps.

docs/specs/archived/2026-04-15-internal-notify-endpoint/tasks.md (1)

1-8: Archived task record looks complete and consistent.

This is a good shipped checklist snapshot and aligns with the archived spec lifecycle.

docs/specs/2026-04-15-autoplay-diversity/spec.md (1)

1-20: Spec quality is strong and implementation-oriented.

The objective, ranking approach, and verification plan are concrete and easy to execute.

docs/specs/archived/2026-04-15-internal-notify-endpoint/spec.md (1)

1-23: Well-documented shipped spec with good operational traceability.

The archived record is clear, includes verification evidence, and links back to the shipping PR.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud