docs: add project roadmap with framework comparison

[ElFantasma]

Summary

• Add docs/PLAN.md with project roadmap informed by framework comparison analysis
• Compares spawned with Erlang/OTP, Akka, Orleans, Actix, and Ractor
• Identifies critical API issues (Improve type safety for request/reply message handling #144, Circular dependency problem with bidirectional actor communication #145) to address before Phase 2
• Documents phase priorities and v0.6+ considerations

Addresses #124

[github-actions]

🤖 Kimi Code Review

This is a documentation PR that adds a strategic roadmap document. Since it's documentation rather than code, I'll focus on clarity, accuracy, and completeness rather than code-specific issues.

Issues found:

1. Line 44-45: The "What's Missing" section lists "Pid/actor identity" but this seems to conflict with the existing ActorRef<T> which provides identity. Consider clarifying whether this refers to a more fundamental identity system (like Erlang's PIDs) or if it's redundant.

2. Line 72: The priority ordering rationale mentions "Error Handling before Supervision" but the table shows Phase 2 (Error Handling) as P1 and Phase 4 (Supervision) as P3, which is consistent. However, the table shows Phase 3 (Process Primitives) as P2, which seems to contradict the rationale text that says "Process Primitives before Supervision". The rationale should be updated to reflect the actual ordering.

3. Line 89-90: The v0.6+ considerations table lists "Actor naming beyond Registry" as a feature, but Phase 3 already includes "Process Primitives (Pid, Registry, Links)". This seems redundant - clarify if this refers to additional naming schemes beyond basic registry.

4. Line 104: "Keep Current Approach" section mentions "Explicit actor lifecycle" but the framework comparison table notes that spawned uses "explicit lifecycle" while Orleans uses "auto-activation". This is slightly inconsistent terminology - consider standardizing.

Minor suggestions:

• Consider adding estimated timelines or complexity ratings to the phases
• The "References" section could include links to the actual GitHub issues for easier navigation
• Consider adding a "Success Metrics" section to define what completion looks like for each phase

Overall, the roadmap is well-structured and provides clear guidance for the project's evolution.

---

Automated review by Kimi (Moonshot AI) · custom prompt

[github-actions]

🤖 Codex Code Review

No code changes in this PR; it only adds documentation at docs/PLAN.md. I don’t see any correctness, concurrency, performance, or actor-lifecycle risks introduced.

If you want code review coverage, point me at a PR with code changes.

---

Automated review by OpenAI Codex · custom prompt

[greptile-apps]

Greptile Overview

Greptile Summary

Added docs/PLAN.md documenting the project roadmap with comprehensive framework comparison analysis covering Erlang/OTP, Akka, Orleans, Actix, and Ractor. The document establishes clear phase priorities (P0-P4) and highlights critical API issues (#144, #145) that should be addressed before Phase 2 development.

Key additions:

• Framework comparison table showing spawned's current capabilities vs established frameworks
• Analysis of what spawned has (clean request/send separation, type-safe messaging, dual execution modes) and what's missing (supervision trees, registry, persistence, clustering)
• Phased roadmap prioritizing API design fixes before building additional features
• Design decisions documenting what approaches to keep vs adopt from other frameworks
• v0.6+ feature considerations for future development

Confidence Score: 5/5

• This PR is safe to merge with no risk - it's a documentation-only addition
• The PR only adds a new documentation file without modifying any code. The content is well-researched, accurately reflects the current codebase capabilities (verified Actor trait, timers, signals, dual execution modes), and provides strategic direction for the project
• No files require special attention

Important Files Changed

Filename	Overview
docs/PLAN.md	Added comprehensive roadmap document comparing spawned with major actor frameworks and defining phase priorities

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant PR as PR #146
    participant Repo as Repository
    participant Issue124 as Issue #124
    
    Dev->>Issue124: Reviews framework comparison request
    Dev->>Repo: Analyzes existing codebase
    Note over Dev,Repo: Studies Actor trait, ActorRef,<br/>timers, streams, signals
    Dev->>Repo: Compares with Erlang/OTP, Akka,<br/>Orleans, Actix, Ractor
    Dev->>PR: Creates docs/PLAN.md
    Note over PR: Documents Phase 1 completion<br/>Framework comparison table<br/>Critical API issues (#144, #145)<br/>Phase priorities (P0-P4)<br/>v0.6+ considerations
    PR->>Repo: Adds strategic roadmap
    Note over Repo: Establishes development priorities<br/>before Phase 2

Loading