docs: replace PLAN.md with focused ROADMAP.md

[ElFantasma]

Summary

• Removes docs/PLAN.md which mixed roadmap with framework comparison and API design analysis
• Creates docs/ROADMAP.md with only the roadmap: completed phases, next steps, and future considerations
• Design research and framework comparisons are already covered in PR docs: API alternatives design documents #154

What changed

• Phase 1 (v0.4) and Phase 2 (v0.5) marked as complete
• Phase 3 (Supervision Trees) is the next milestone, targeting v1.0.0
• Dropped Pid from the plan (not part of our design), kept Links/Monitors as supervision building blocks
• Removed the standalone "Error Handling" phase — error concerns fold into supervision work
• 250 lines → 60 lines

[github-actions]

🤖 Claude Code Review

PR #162 Review: docs: replace PLAN.md with focused ROADMAP.md

This is a pure documentation change — no code modifications.

---

Summary

Replaces the 250-line PLAN.md (a mix of roadmap, framework comparison tables, API design rationale, and issue analysis) with a focused 60-line ROADMAP.md that tracks only project phases and future considerations.

---

What's Good

• Separation of concerns is correct. PLAN.md was doing too many things at once: roadmap, competitive analysis, API design decisions. Splitting it out makes each artifact more useful.
• The new ROADMAP.md is accurate. Phase 1 and Phase 2 items match what's actually in the codebase (lifecycle hooks, Handler<M>, Recipient<M>, macros, registry).
• Phase 3 scope is well-defined. Links, Monitors, supervision strategies, and meltdown protection are the right building blocks, and the order (Links → Monitors → Supervisor → Trees → Meltdown) is logical.
• The References section is improved — ROADMAP.md correctly points to PR #154 for the design research that was removed, so the information isn't lost, just relocated.

---

Minor Issues

Phase 4 is bundled with v1.0.0 alongside Phase 3. Both phases target v1.0.0:

Phase 3: Supervision Trees — Target: v1.0.0
Phase 4: Documentation & Polish — v1.0.0

This conflates feature work with documentation under the same version tag, which could be misleading about what constitutes the v1.0.0 release. Consider either giving Phase 4 its own version target (e.g., v1.0.0 for supervision, v1.1.0 for polish) or noting that Phase 4 is a prerequisite for shipping v1.0.0 rather than a separate phase.

send_message_on() in Phase 1 is listed as a completed feature but the current API in CLAUDE.md doesn't mention it. Minor — likely fine if it still exists in the codebase, but worth a quick verify so the history section stays accurate.

#[actor] macro description is vague. "derives Actor + Handler<M> boilerplate" — it's unclear to readers whether this is a derive macro or attribute macro, and what exactly it generates. Since this is a user-facing doc, a one-liner like derives Actor impl and the message dispatch glue would help.

---

Verdict

The refactor is sound. The one actionable note worth addressing before merge: clarify whether Phase 4 is a sub-phase of v1.0.0 or a post-release polish step, to avoid ambiguity about what ships under that version tag. Everything else is cosmetic.

---

Automated review by Claude (Anthropic) · sonnet · custom prompt

[github-actions]

🤖 Codex Code Review

Findings

1. Low: the PR creates a second, conflicting roadmap source instead of replacing the existing one. The new file says Phase 3 is supervision trees and Phase 4 is docs/polish targeting v1.0.0 in docs/ROADMAP.md:22 and docs/ROADMAP.md:35, but the README still advertises a different roadmap centered on observability, custom runtime, preemptive scheduling, virtual actors, etc. in README.md:196. That leaves users with two incompatible “official” plans. I’d either update the README to link to docs/ROADMAP.md as the single source of truth, or fold this new content into the existing README roadmap section.

No implementation, concurrency, lifecycle, or memory-safety issues surfaced here otherwise. The patch is docs-only, and deleting docs/PLAN.md does not leave broken references in the repository.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[github-actions]

🤖 Kimi Code Review

This is a documentation-only change (replacing PLAN.md with ROADMAP.md). No code changes to review for concurrency, safety, or performance.

Documentation Accuracy Checks

Verify these align with the actual implementation (v0.5):

• Line 5 (ROADMAP.md): started() / stopped() lifecycle — Confirm these are the exact method names in the Actor trait. The previous doc used init() / teardown().
• Line 6: ActorRef<A> — Verify the type parameter is A (not T as in the old doc). If the codebase uses T, this should match.
• Line 14: #[protocol] macro generating XRef type aliases — Ensure XRef is the documented naming convention (e.g., MyActorRef vs XRef).
• Phase 2 claims: All items marked ✅ should be implemented in PR feat: #[protocol] + #[actor] macros, Handler<M>, registry (0.5.0) #153. If any are still pending, remove the checkmark to avoid user confusion.

Content Review

• Lost context: The deleted PLAN.md contained detailed framework comparisons and design rationales (why Handler<M> vs RpcReplyPort, supervision strategies). If this content isn't moving to docs/design/ or ADRs, consider keeping a condensed version—the comparison matrix was valuable for users choosing between Spawned/Actix/Ractor.
• Consistency: The new doc mentions "Named registry" in Phase 2, but Phase 3 mentions "Links/Monitors". Ensure Phase 2's registry isn't confused with Phase 3's "Process registry" (if those are different features).

Nit

• Line 5: Consider clarifying that started()/stopped() are lifecycle hooks (async or sync?) to match the trait signature.

No blocking issues. Acknowledge if the API surface described matches the implementation.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[greptile-apps]

Greptile Summary

This is a focused documentation clean-up that replaces the 250-line docs/PLAN.md with a leaner 60-line docs/ROADMAP.md. The old document combined a project roadmap with framework comparison tables (Spawned vs Actix vs Ractor), Erlang alignment analysis, and deep API-design rationale — content that is now better handled in PR #154's dedicated design docs. The new ROADMAP.md is strictly a forward-looking milestone tracker: two completed phases (v0.4 core actor framework, v0.5 multi-message API), Phase 3 supervision trees as the next target for v1.0.0, and a future-considerations table. References to both the old design issues (#144, #145) and the framework-comparison PR (#154) are preserved in the References section, so nothing is lost.

Key changes:

• Phase 1 lifecycle description updated from the old init() / teardown() naming to started() / stopped(), reflecting the post-Phase-2 API surface.
• Pid dropped from the plan (not part of the current design); Links and Monitors retained as supervision building blocks.
• Standalone "Error Handling" phase removed — those concerns are folded into Phase 3 supervision work.
• Framework comparison, design-decision tables, and detailed API-issue write-ups removed from the roadmap; they live in PR docs: API alternatives design documents #154 and referenced issues.

Confidence Score: 5/5

Pure documentation change with no code impact; safe to merge immediately.

All changes are in Markdown documentation files only. No logic, no tests, no APIs are touched. The new ROADMAP.md is coherent, well-structured, and the rationale for every removal is clearly explained in the PR description. No P0 or P1 findings.

No files require special attention.

Important Files Changed

Filename	Overview
docs/PLAN.md	Deleted: 250-line document mixing roadmap, framework comparison tables (Spawned vs Actix vs Ractor), critical API issues analysis, and design decisions — content split between the new ROADMAP.md and PR #154.
docs/ROADMAP.md	Added: Clean 60-line roadmap covering 4 phases (two completed, two upcoming) plus a future considerations table; lifecycle method names updated from the old init()/teardown() style to the Phase 2 started()/stopped() API.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P1["Phase 1 — v0.4 ✅\nCore Actor Framework\nActor trait · ActorRef · Timers · Streams · Signals"]
    P2["Phase 2 — v0.5 ✅\nType-Safe Multi-Message API\nHandler<M> · Recipient<M> · #[protocol] · #[actor] · Registry"]
    P3["Phase 3 — next (v1.0.0)\nSupervision Trees\nLinks · Monitors · Supervisor · OneForOne / OneForAll / RestForOne\nSupervision hierarchy · Meltdown protection"]
    P4["Phase 4 — v1.0.0\nDocumentation & Polish\nAPI docs · Guides · Migration guide · Examples"]
    FUTURE["Post-v1.0 Considerations\nProcess groups · Priority channels\nState machines · Backoff · Dynamic supervisors\nPersistence · Clustering"]

    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> FUTURE

    style P1 fill:#22c55e,color:#fff
    style P2 fill:#22c55e,color:#fff
    style P3 fill:#3b82f6,color:#fff
    style P4 fill:#3b82f6,color:#fff
    style FUTURE fill:#a855f7,color:#fff

Loading

_{Reviews (1): Last reviewed commit: "docs: replace PLAN.md with focused ROADM..." | Re-trigger Greptile}