diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6ca971f --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# Session state files (local only, not tracked) +REMEMBER.md +TODO.md +ROADMAP.md + +# OS files +.DS_Store +Thumbs.db diff --git a/plugins/linkedin-thought-leadership/ROADMAP.md b/plugins/linkedin-thought-leadership/ROADMAP.md deleted file mode 100644 index 17559c2..0000000 --- a/plugins/linkedin-thought-leadership/ROADMAP.md +++ /dev/null @@ -1,134 +0,0 @@ -# LinkedIn Thought Leadership Plugin — Roadmap - -**Current version:** v1.1.0 (April 2026) -**Scope:** Planned improvements through Q4 2026 - -Items organized by quarter and track. Priority = Impact / Effort (High/Medium/Low). Items within each quarter ordered by priority. - ---- - -## Q2 2026 (April-June) - -### Onboarding & First-Run Experience -**Priority: High** | **Effort: Low** - -- [x] First-run welcome flow in session-start hook -- [x] Condensed getting-started menu for zero-post users in `/linkedin` router -- [x] Readiness check in `/linkedin:post` and `/linkedin:quick` for unpersonalized state -- [x] Inline 5x5x5 engagement ritual explanation -- [x] `/linkedin:onboarding` — dedicated multi-step onboarding command that guides profile → setup → first-post as one flow -- [x] README Quick Start refinement — 5-minute getting-started path with single `/linkedin:onboarding` entry point - -### Content Quality -**Priority: High** | **Effort: Medium** - -- [x] Enhanced voice-trainer agent: automatic drift scoring on every post draft (compare against voice samples) -- [x] Content Matrix improvements: add industry-specific angle variants -- [x] Carousel post support: structured multi-slide content generation with visual layout guidance -- [x] `/linkedin:react` enhancement: multi-URL comparison posts (compare 2-3 articles) - -### Analytics Pipeline -**Priority: Medium** | **Effort: Medium** - -- [x] Automated week-rollover: session-start hook resets `posts_this_week` and updates `current_week` on week change -- [x] Post-level heatmap generation: day-of-week performance matrix from imported CSV data (time-of-day not available in CSV export) -- [x] `/linkedin:report` month-over-month comparison view - -### Algorithm Reference Update (April 2026) -**Priority: High** | **Effort: Low-Medium** - -LinkedIn's 2026 algorithm introduced significant changes since the January 360Brew update. The plugin's reference documents and commands need updating to reflect current data. - -- [x] Carousel optimal slide count: update from 12 to 7 slides (18% better performance). Updated `algorithm-signals-reference.md`, `carousel-templates.md`, `carousel.md` quality checklist -- [x] Carousel reach multiplier: update from 1.6x to 3.4x vs single-image. Clarified engagement rate (24.42% was PDF-specific, carousel-specific is 1.92%). Added 35% click-through threshold penalty -- [x] Video format overhaul: vertical 9:16 gets distribution boost (3-4x watch duration vs landscape). Updated recommended max from 90s to 60s. Added 30% completion rate gate. Updated 12 files -- [x] Depth Score concept: added new section to `algorithm-signals-reference.md` — LinkedIn's primary ranking metric measuring actual engagement duration -- [x] Delayed engagement boost: added 4-6x boost for 24-72h post-publication engagement. Updated distribution model -- [x] 90-day topic alignment requirement: updated 360Brew validation section with 90-day categorization requirement -- [x] Organic reach decline context: added "2026 Reach Context" section (-47% YoY overall, -72% video, -34% text) -- [x] Engagement pod detection hardened: strengthened negative signals and red flags with LinkedIn VP statement and detection mechanisms - ---- - -## Q3 2026 (July-September) - -### Claude Code Platform Integration -**Priority: High** | **Effort: Medium-High** - -- [ ] Hook event expansion: leverage new Claude Code hook events as they become available for richer automation -- [ ] Subagent improvements: parallel content generation in `/linkedin:batch` using Claude Code's evolving subagent capabilities -- [ ] MCP server for analytics: expose analytics data as MCP resources for cross-plugin access - - *Blocked on:* Claude Code MCP server authoring stabilization - -### Analytics & Intelligence -**Priority: High** | **Effort: Medium** - -- [ ] Trend detection across 4+ weeks of imported data (analytics-interpreter agent) -- [ ] Benchmark database: anonymized performance baselines by niche and follower count -- [ ] A/B test auto-analysis: when experiment duration ends, surface winner with statistical confidence -- [ ] Content fatigue detection: alert when engagement drops on a recurring content pillar - -### Content Strategy -**Priority: Medium** | **Effort: Medium** - -- [ ] Video-first strategy: LinkedIn prioritizes native video — add video-specific hooks and scheduling guidance -- [ ] AI-generated image support via MCP image tools for post visuals and carousel slides -- [ ] Multi-language support: translate posts while preserving voice characteristics - - *Blocked on:* Voice profile internationalization design - ---- - -## Q4 2026 (October-December) - -### Advanced Content -**Priority: Medium** | **Effort: High** - -- [ ] LinkedIn Newsletter integration: `/linkedin:newsletter` command for long-form content strategy (requires 5K+ followers gate) -- [ ] LinkedIn Article workflow: `/linkedin:article` with SEO optimization for LinkedIn's article platform -- [ ] Seasonal content library: pre-built content hooks for recurring Q1-Q4 events and industry moments -- [ ] Document/PDF carousel generation: create downloadable slide decks from post content - -### Architecture & Reliability -**Priority: Medium** | **Effort: Medium** - -- [ ] State file schema migration tool: handle breaking changes between plugin versions gracefully -- [ ] Hook performance audit: measure execution time per hook, identify bottlenecks -- [ ] E2E test suite for hooks: automated testing beyond the analytics pipeline -- [ ] Plugin self-update check: compare installed version against marketplace version - -### Growth & Monetization -**Priority: Low** | **Effort: Medium** - -- [ ] Competitor tracking persistence: store competitive analysis results for trend comparison over time -- [ ] Lead generation templates: content-to-DM pipeline for consulting/speaking inquiries -- [ ] Collaboration matching: suggest collaboration partners based on audience overlap analysis - ---- - -## Deprioritized (Not in 2026 scope) - -| Item | Reason | -|------|--------| -| LinkedIn API direct posting | No official posting API available; copy-paste workflow is intentional and avoids ToS issues | -| Multi-user / team support | Designed for individual thought leaders; team features would change the architecture fundamentally | -| Real-time analytics streaming | LinkedIn doesn't expose streaming data; CSV export is the only reliable data source | -| Automated engagement (auto-like, auto-comment) | Violates LinkedIn Terms of Service; plugin explicitly avoids this | -| OAuth login for LinkedIn data | LinkedIn's API access is restrictive; manual CSV export is more reliable and privacy-respecting | - ---- - -## Dependencies on External Development - -| Dependency | Impacts | Status | -|------------|---------|--------| -| Claude Code hook events (new event types) | Q3 automation improvements | Monitor Claude Code changelogs | -| Claude Code MCP server authoring | Q3 analytics MCP server | In development (as of April 2026) | -| Claude Code subagent API stability | Q3 batch generation | Available but evolving | -| LinkedIn CSV export format stability | All analytics features | Stable (no changes since Jan 2026) | -| MCP image generation tools | Q3 visual content | Available via mcp-image | - ---- - -## How to Contribute Ideas - -File an issue at the plugin's marketplace repository. Bug reports and feature requests are welcome. diff --git a/plugins/ultraplan-local/docs/ROADMAP.md b/plugins/ultraplan-local/docs/ROADMAP.md deleted file mode 100644 index aa93389..0000000 --- a/plugins/ultraplan-local/docs/ROADMAP.md +++ /dev/null @@ -1,338 +0,0 @@ -# ultraplan-local Roadmap - -## Vision - -ultraplan-local is a **deep planning specialist**. It does one thing: creates -plans so thorough they can be implemented without questions. - -**The plan is the product.** Everything else exists to make the plan better. - -### What we ARE -- The most thorough planning process available as a Claude Code plugin -- Autonomous: gathers all information itself, needs no human help along the way -- Plans that stand on their own — implementable by someone who has never seen the codebase - -### What we are NOT -- Not a project engine (that's Harness) -- Not a behavior framework (that's Superpowers) -- Not an execution engine, team manager, or issue tracker -- Not optimized for infrastructure-as-code (Terraform, Helm, Pulumi) — the agents - are designed for application code. IaC projects get a result, but agents like - architecture-mapper and test-strategist provide less value there. - -### Quality Goals -A plan from ultraplan-local should: -1. Be implementable without asking questions -2. Have testable verification criteria for each step -3. Contain no placeholders, TBDs, or vague instructions -4. Include TDD structure where the project uses tests -5. Have a quantitative assessment of its own quality (score A-D) - ---- - -## v0.4.0 — Information-Complete and Plan Quality (DONE) - -Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details. - -**Delivered:** -- 3 new agents: task-finder, git-historian, spec-reviewer -- All agents run for all codebase sizes (turns scale, not agent count) -- No-placeholder rule in plan-critic (TBD/TODO = blocker) -- Quantitative plan scoring (A-D grades, 5 weighted dimensions) -- `[ASSUMPTION]` marking with threshold warning (>3 = warning) -- Spec-reviewer as new phase before exploration - ---- - -## v1.0.0 — Production-Ready Plugin - -Two pillars: (1) features that close real user friction, and (2) repo infrastructure -for a credible open-source project. - -Each feature item has a **Rationale** tracing back to a role simulation -or research finding. - -### Pillar 1: Plugin Features - -#### 1. `--quick` mode - -New mode that skips the exploration phase. Plans directly from interview plus -minimal file checking (Glob/Grep to verify file paths mentioned in the conversation). - -``` -/ultraplan-local --quick Add rate limiting to the API -``` - -Flow: interview → spec → plan (without agent swarm) → adversarial review → done. - -Useful when: -- The developer knows the code well and needs structure, not mapping -- The codebase is small and simple -- The time/cost of full exploration isn't worth it - -**Rationale:** Solo developer simulation revealed that 6 agents on 12 files feels -like overkill when the developer already knows the code. git-historian provides zero -value for solo projects with short history. - -**Changes:** `commands/ultraplan-local.md` (new mode parsing), `agents/planning-orchestrator.md` -(new quick path that skips Phase 2). - -#### 2. `--export pr` for shareable plan output - -Generates a PR-ready summary from an existing plan: - -``` -/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md -``` - -Output: a markdown block formatted as a PR description (Summary, Changes, Test plan) -that can be copied directly into a PR. - -Possible export formats: -- `pr` — PR description with summary and test plan -- `issue` — issue comment with plan summary -- `markdown` — clean plan without internal metadata (score, revisions) - -**Rationale:** OSS contributor simulation showed that the plan is a local file with no -easy way to share. The user wanted to share with a maintainer for approval before -implementation. - -**Changes:** `commands/ultraplan-local.md` (new `--export` mode parsing and output format). - -#### 3. task-finder categorization - -Update the task-finder agent to categorize findings into three levels: - -| Category | Meaning | Example | -|----------|---------|---------| -| **Must-change** | Files that must be modified to implement the task | `src/auth/middleware.ts` | -| **Must-respect** | Interfaces and contracts that must be honored | `src/types/auth.d.ts` | -| **Reference** | Useful context, but no changes needed | `src/utils/jwt.ts` | - -**Rationale:** Senior engineer simulation (2000+ files) revealed that task-finder -reported 47 files in a flat list. Without prioritization, it's useless for -planning. - -**Changes:** `agents/task-finder.md` (updated output format and instructions). - -#### 4. Adaptive interview depth - -The interview adapts to the user's response depth: - -- **Detailed answers** (>2 sentences, technical language): ask fewer, more targeted questions. - Assume the user is senior and knows what they want. -- **Short/uncertain answers** (<1 sentence, "don't know"): ask simpler questions, offer - alternatives instead of open-ended questions. For bugs: focus on reproduction - ("What do you see?" / "What did you expect?") instead of technical requirements. - -**Rationale:** Junior developer simulation showed that the interview assumes the user -understands the problem. The junior didn't know enough to answer open-ended questions well, -resulting in a thin spec and a C-grade plan. - -**Changes:** `commands/ultraplan-local.md` (updated Phase 2 interview instructions). - -#### 5. Complete `plugin.json` metadata - -Add missing fields for marketplace readiness: - -```json -{ - "name": "ultraplan-local", - "version": "1.0.0", - "description": "...", - "author": "Kjell Tore Guttormsen", - "homepage": "https://git.fromaitochitta.com/open/ultraplan-local", - "repository": "https://git.fromaitochitta.com/open/ultraplan-local.git", - "license": "MIT", - "keywords": ["planning", "implementation", "agents", "adversarial-review"] -} -``` - -**Rationale:** Plugin ecosystem research showed that `plugin.json` is missing 5 of -the fields that marketplace and discovery tools use. Highest leverage gap for -distribution. - -**Changes:** `.claude-plugin/plugin.json`. - -#### 6. Documented IaC limitation in README - -Add a section in README under "When to use" that explicitly states that -ultraplan-local is designed for application code, and that IaC projects -(Terraform, Helm, Pulumi, CDK) get reduced value from the exploration agents. - -**Rationale:** DevOps simulation showed that architecture-mapper looks for -src/lib/controllers (irrelevant for Terraform), test-strategist doesn't know -infra testing tools, and the plan misses Terraform-specific steps like state locking. - -**Changes:** `README.md` (new section in the "When to use" section). - -### Pillar 2: Repo Infrastructure - -#### 7. Forgejo issue templates - -Create `.forgejo/ISSUE_TEMPLATE/` with two YAML templates: - -**`bug_report.yaml`:** -- Plugin version (required) -- Claude Code version -- Reproduction steps -- Expected vs actual behavior -- Auto-label: `type: bug` - -**`feature_request.yaml`:** -- Problem description -- Proposed solution -- Alternatives considered -- Auto-label: `type: enhancement` - -**Rationale:** Forgejo audit showed no `.gitea/` or `.forgejo/` infrastructure. -Standard for an open-source project that accepts issues. - -#### 8. Label set in Forgejo - -Create via Forgejo API or UI: - -| Label | Color | Use | -|-------|-------|-----| -| `type: bug` | red | Something is broken | -| `type: enhancement` | blue | New feature or improvement | -| `type: docs` | green | Documentation only | -| `status: confirmed` | yellow | Verified/accepted | -| `status: wontfix` | gray | Closed without action | -| `good first issue` | purple | Low complexity, well scoped | - -**Rationale:** No labels exist. Necessary for triage. - -#### 9. Forgejo Release for v1.0.0 - -Create a Release object (not just a git tag) with CHANGELOG content attached. -Use `v1.0.0` as the tag name. - -**Rationale:** Repo audit showed that commits exist but no Release objects. -Releases are the first thing users see on a Forgejo project. - -#### 10. README badges - -Add badges to README: - -```markdown -![Version](https://img.shields.io/badge/version-1.0.0-blue) -![License](https://img.shields.io/badge/license-MIT-green) -![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) -``` - -**Rationale:** Quality signal on first visit. Standard for open source. - -#### 11. CONTRIBUTING.md tailored for solo project - -Rewrite to be honest about the contribution model: -- "This is a solo project. Issues are welcome. PRs are considered but not expected." -- Remove section about PR workflow -- Keep: how to report bugs, suggest improvements - -**Rationale:** Current CONTRIBUTING.md implies that PRs are welcome, but -the project is marked as solo. Dishonest signaling. - ---- - -## v1.3.0 — Session-Aware Parallel Execution (DONE) - -Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details. - -**Delivered:** -- `/ultraexecute-local` auto-detects `## Execution Strategy` in plans -- Multi-session parallel orchestration via `claude -p` per wave -- `--fg` flag: force sequential execution, ignore Execution Strategy -- `--session N` flag: execute only session N (used by child processes) -- Phase 2.5 (Execution strategy decision) and Phase 2.6 (Multi-session orchestration) -- Execution Strategy section in plan template (sessions, waves, scope fences) -- planning-orchestrator generates Execution Strategy for plans with > 5 steps -- File overlap analysis to group steps into sessions and waves - ---- - -## v1.2.0 — Disciplined Plan Executor (DONE) - -Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details. - -**Delivered:** -- `/ultraexecute-local` command: 9-phase workflow for disciplined plan execution -- 4 modes: execute, --resume, --dry-run, --step N -- Per-step protocol: implement → verify → on-failure → checkpoint -- Progress file for crash recovery and resume -- Entry/exit condition checking for session specs -- Scope fence enforcement (never-touch protection) -- JSON summary block for headless log parsing -- Stats tracking to ultraexecute-stats.jsonl -- Positioning: Harness = project engine, Kiur = TDD, Ultraexecute = plan executor - ---- - -## v1.1.0 — Headless Multi-Session Execution (DONE) - -Completed 2026-04-06. See [CHANGELOG.md](../CHANGELOG.md) for details. - -**Delivered:** -- `--decompose` mode: splits plan into self-contained headless sessions -- `--export headless` format: shortcut to decompose -- session-decomposer agent: analyzes step dependencies, groups into sessions, generates dependency graph + launch script -- Session spec template with scope fences, entry/exit conditions, failure handling -- Failure recovery per step in plan template: On failure + Checkpoint -- Headless readiness as new dimension in plan-critic (9 dimensions, rebalanced weights) - ---- - -## Future (after v1.1, unprioritized) - -Based on competitive analysis and simulations. Each item has a rationale -for why it's not in v1.0. - -| Feature | Source | Why not v1.0 | -|---------|--------|--------------| -| Plan auto-update during execution | Windsurf differentiator | Major architecture change — the plan is currently static after generation. Requires hooks that observe execution and update the plan file. Windsurf spent months on this. | -| Issue integration (`--issue #42`) | OSS contributor simulation | Tracker-dependent (Linear, Forgejo, GitHub, Jira). Too ambitious for first stable release. | -| Plan diff on re-planning | Senior engineer simulation | Useful but not a blocker. Can be solved with `diff` on two plan files manually. | -| Cost estimate in plan summary | Senior engineer simulation | Requires reliable token counting. Claude Code API doesn't expose this directly. | -| IDE sidebar for plan | Windsurf differentiator | Requires VS Code extension — entirely different technology stack. | -| IaC-adapted agents | DevOps simulation | Niche need. Solved with documented limitation in v1.0. | -| Bug mode (`--bug`) | Junior simulation | Can be partially solved with adaptive interview (v1.0 item 4). Dedicated mode is overkill for first release. | -| Solution memory | Roadmap v0.4.0 future | Secondary — plan quality should stand on its own without history. | - ---- - -## Competitive Position - -### What ultraplan-local has that nobody else does - -| Feature | Copilot Workspace | Cursor | Windsurf | ultraplan-local | -|---------|-------------------|--------|----------|----------------| -| Adversarial review (plan-critic + scope-guardian) | No | No | No | **Yes** | -| Quantitative plan scoring (A-D) | No | No | No | **Yes** | -| No-placeholder enforcement (hard blocker) | No | No | No | **Yes** | -| `[ASSUMPTION]` marking with threshold warning | No | No | No | **Yes** | -| Spec-driven headless mode (`--spec`) | No | No | No | **Yes** | -| TDD-structured steps (RED-GREEN-REFACTOR) | No | No | No | **Yes** | -| Full interview phase for requirements gathering | No | No | Partial | **Yes** | -| 12 specialized agents | No | No | No | **Yes** | -| Session decomposition into headless sessions | No | No | No | **Yes** | -| Failure recovery per step (On failure/Checkpoint) | No | No | No | **Yes** | -| Parallel wave-based execution (`launch.sh`) | No | No | No | **Yes** | - -### Known gaps vs competitors - -| Gap | Who has it | Status | -|-----|-----------|--------| -| Plan updates during execution | Windsurf | Future — major architecture change | -| PR-native output | Copilot Workspace | v1.0 — `--export pr` | -| Issue integration | Copilot Workspace | Future — tracker-dependent | -| Sandbox execution during planning | Cursor | Out of scope — different architecture | -| IDE sidebar | Windsurf | Future — requires VS Code extension | - ---- - -## Compatibility - -- **Harness users**: Plans from ultraplan are detailed enough to - manually decompose into Harness feature_list.json -- **Superpowers users**: TDD task structure matches Superpowers' - plan format. Plans are compatible with the `executing-plans` skill.