[roadmap] Agentize Framework Enhancement Roadmap

[were]

Overview

This roadmap outlines enhancement opportunities for the agentize framework across its three automation levels:

Level	Current State	Enhancement Focus
Micro	Hook-based permissions, session state, auto-continuation	Configurability, robustness
Macro	Server polling, worker pool, GitHub Projects	Event-driven, observability
One-time	Commands as natural language scripts	Dry-run, composition

---

P0: Production Essentials

1. Error Recovery & Retry Mechanism

Problem: Worker crashes result in silent failures; no automatic retry.

Proposal:

• Add retry_count to session state with configurable MAX_RETRIES
• Failed issues (after max retries) get agentize:failed label for human triage
• Leverage existing milestone checkpoints for resumption

Files: python/agentize/server/workers.py, .claude-plugin/lib/session_utils.py

---

P1: User Experience

2. Dry-Run Mode for Commands

Problem: Users must trust commands completely; no preview mechanism.

Proposal:

• Add --dry-run flag to critical commands
• /ultra-planner --dry-run: Show planned issue without creating
• /issue-to-impl --dry-run: Show execution plan without branching

Files: .claude-plugin/commands/*.md

3. Observability Dashboard

Problem: Monitoring relies on Telegram notifications and scattered log files.

Proposal:

• Centralized metrics collection in .tmp/metrics/
• lol serve --dashboard option for local web UI
• Track: success rate, avg duration, permission decision distribution

Files: python/agentize/server/, src/cli/lol/commands/

---

P2: Extensibility

4. Configurable Permission Rules

Problem: rules.py is hardcoded; different projects need different rules.

Proposal:

• Support project-specific rules in .agentize.yaml
• Allow pattern-based allow/deny overrides
• Keep hardcoded rules as defaults

# .agentize.yaml
permissions:
  allow:
    - pattern: "npm run deploy:staging"
  deny:
    - pattern: "npm run deploy:prod"

Files: .claude-plugin/lib/permission/rules.py, python/agentize/server/runtime_config.py

5. Event-Driven Architecture (Won't Do)

Problem: 5-minute polling delays response to label changes.

Decision: As per offline discussion, this is over-engineering for the current use case:

• Webhook integration requires exposing a public endpoint, handling HTTPS certificates, and replay attack prevention
• The current polling model is simpler and more secure (no inbound connections needed)
• Polling interval is already configurable via --period flag
• Wasting some API rate limit is acceptable; if faster response is needed, reduce the period

---

P3: Advanced Features

6. Workflow Composition

Problem: Complex workflows require manual command chaining.

Proposal:

• Declarative workflow definition files
• Support wait_for conditions between steps
• Example: feature-request → plan → impl → PR → merge

# .claude-plugin/workflows/full-cycle.yaml
steps:
  - command: /ultra-planner --from-issue {issue_no}
    wait_for: plan_accepted
  - command: /issue-to-impl {issue_no}
    wait_for: tests_pass

Files: New .claude-plugin/workflows/ directory

7. Priority Queue

Problem: All issues treated equally; no urgency expression.

Proposal:

• Support priority:high/medium/low labels
• Server processes high-priority issues first
• Optional: Leverage GitHub Projects Priority field

Files: python/agentize/server/github.py

8. Multi-Repository Support

Problem: One server instance serves one repository only.

Proposal:

• Multi-repo configuration in .agentize.local.yaml
• Independent worker pools per repository
• Unified monitoring across repos

Files: python/agentize/server/runtime_config.py, python/agentize/server/__main__.py

---

Implementation Notes

• Each item should be a separate issue when ready for implementation
• P0 items are prerequisites for production deployment
• P1 items significantly improve adoption friction
• P2/P3 items are nice-to-have for power users

---

Related

• Current architecture documented in source READMEs
• Permission system: .claude-plugin/lib/permission/
• Server module: python/agentize/server/
• Hook system: .claude-plugin/hooks/