Appearance
Kendo App Plans Landscape
Summary
Analysis of 97 plan directories in ~/Code/kendo/docs/plans/, spanning the full history of Kendo's engineering effort. The plans cover 13 distinct feature domains, contain 224+ architectural decisions (almost all accepted), and show a clear evolution from minimal task lists to structured plan-and-decide workflows. The heaviest investment areas are permissions/RBAC (3 major plans, 31 decisions), multi-tenancy/architecture (5 plans, 18 decisions), and MCP tooling (8 plans). 54 plans are fully completed; 12 are materially stalled; the rest are in progress. The planning format improved dramatically around the KD-0157 era, when DECISIONS.md was introduced as a separate artifact.
1. Feature Landscape — Where Has Engineering Effort Concentrated?
Domain Categorization (97 plans)
| Domain | Plan Count | Key Plans | Decisions |
|---|---|---|---|
| MCP Tooling | 8 | KD-0101, KD-0106, KD-0166 (x2), KD-0167 (x2), KD-0168, KD-0224, KD-0320, KD-XXXX | 17 |
| Permissions / RBAC | 3 | KD-0115-0117, KD-0315, KD-0340 | 31 |
| Multi-Tenancy / Architecture | 5 | IT-130, KD-0190, KD-0193-0195, KD-0205-0208 | 18 |
| UI / UX Polish | 13 | IT-0072, IT-0095, IT-0188, KD-0163, KD-0166-fix, KD-0170, KD-0249, KD-0254, KD-0278, KD-0283, KD-0284, KD-0301, KD-0304 | 18 |
| Time Tracking | 4 | KD-0097, KD-0153, KD-0161, KD-0311 | 0 |
| AI Features | 7 | KD-0112, KD-0125, KD-0280, KD-0281, KD-0343, KD-0355, ai-prompt-section, ai-workflow-optimization, feature-planner | 15 |
| Reports / Feedback | 4 | KD-0157, KD-0186, KD-0265, KD-0349 | 22 |
| Notifications | 4 | KD-0174, KD-0175, KD-0288, KD-0289, KD-0293, KD-0294, inbox-notifications | 11 |
| Attachments / Files | 3 | KD-0183, KD-0236, KD-0240 | 16 |
| CLI / Distribution | 3 | KD-0237, KD-0261, KD-XXXX-mcp-cli | 21 |
| Authentication / Security | 4 | IT-115, KD-0167-change-pw, KD-0260, KD-0314, KD-0341 | 26 |
| Infrastructure / Shared Code | 7 | KD-0142, KD-0179, KD-0204, KD-0228, KD-0266, KD-0286, KD-0302 | 12 |
| Integrations | 4 | KD-0113, KD-0270, KD-0277, claude-code-sdk | 6 |
| Other | 6 | IT-0073, IT-0079, KD-0102-105, KD-0244, KD-0292, KD-0305, KD-0312, KD-0316, KD-0318, KD-0324, KD-0328, KD-0335, KD-0347, tenancy-refactor | — |
Where the Most Effort Landed
By decision count (proxy for architectural complexity):
Permissions/RBAC — 31 decisions across KD-0315 (23 decisions alone, the single most decision-heavy plan), KD-0340 (8 decisions). This is the most architecturally complex area of the product, touching backend policies, frontend composables, route middleware, role management UI, and security testing.
Authentication/Security — 26 decisions. KD-0341 (OAuth login, 17 decisions) and KD-0260 (email verification, 8 decisions) are full-stack features with significant security considerations.
Reports/Feedback — 22 decisions. The reports system (KD-0186 backend, KD-0265 frontend, KD-0349 attachments) was delivered as a deliberate 3-plan split, each with its own decision log.
CLI/Distribution — 21 decisions. The Go CLI (KD-0237) and its distribution system (KD-0261) required decisions spanning OAuth device flow, GoReleaser, R2 storage, and self-update mechanics.
By plan count (proxy for breadth):
UI/UX Polish — 13 plans. Most are small, focused fixes (clickable rows, avatar colors, sidebar membership display). Low decision count per plan.
MCP Tooling — 8 plans. Kendo's MCP server evolved through incremental tool additions (blocking relations, sprint management, comments, time logs, epics). Each plan is small and focused.
AI Features — 7 plans. Ranging from early experiments (AI time estimation, multi-project bot) to the latest multi-agent pipeline (KD-0355).
2. Decision Archaeology — Architectural Decisions Still Relevant for Future Work
Total Decisions Found
224+ architectural decisions across 37 DECISIONS.md files. Status breakdown:
- Accepted: ~210 (94%)
- Under discussion: 7 (all in KD-0294, notification retention research)
- Superseded: 3 (KD-0236 D2, KD-0315 D8, KD-0315 D10)
- Research/Informational: 1 (KD-0289 D2, watchers system scope analysis)
Decisions That Shape Future Work
Multi-Tenancy and Architecture
| Decision | Plan | Impact on Future Work |
|---|---|---|
| Separate CentralUser model | KD-0190 D1 | Central and tenant auth are completely independent. Any central app auth feature must use CentralUser, not User. |
| Explicit @shared/@tenant/@central aliases | KD-0190 D2 | Import boundaries are enforced by pattern. New shared code must live in @shared/. ESLint rules enforce this. |
| Single Vite instance, multi-entry | KD-0190 D10 | Both apps build with one npm run build. No APP_NAME env var. Blade templates reference $manifest['src/apps/tenant/main.ts']. |
| Test directory mirrors source structure | KD-0190 D8 | Tests live in tests/js/apps/tenant/domains/ mirroring src/apps/tenant/domains/. Central app tests go in tests/js/apps/central/. |
| Factory pattern for shared services | KD-0194 D1 | Pagination, markdown, HTTP, storage all use createXxxService(deps). New shared services should follow this pattern. Toast/modal/error are the exceptions (singletons per KD-0204 D1). |
Permissions System
| Decision | Plan | Impact on Future Work |
|---|---|---|
| 15 permission resources with CRUD+Own | KD-0315 | Every new feature that needs authorization must decide: new resource (ID 16+), or fits existing? KD-0343 already added resources 16-17 for BYOK keys. |
| Project owner bypasses all project-scoped permissions | KD-0315 D17 | PermissionResourceEnum::isProjectScoped() is the authoritative list. Owner bypass is automatic for all 12 project-scoped resources. |
| Always-readable resources | KD-0315 D16 | 12 of 15 resources force can_read: true. Only SystemPrompts, ProjectTokens, Roles, and AppSettings have toggleable read. New resources should evaluate whether read is meaningful to restrict. |
| canInProject() wrapper for frontend | KD-0315 D21 | Project-scoped permission checks must use canInProject(), not can(). The wrapper handles owner bypass. |
Data Patterns
| Decision | Plan | Impact on Future Work |
|---|---|---|
| Reports as lightweight intake, not full issues | KD-0186 D2 | Reports have title + description only. Promotion to issues is the gate. New report-like features should follow this pattern. |
| Hard delete for notifications | KD-0294 D2 | Notifications use hard delete, not soft delete. Only User model uses SoftDeletes in the entire codebase. |
| Token-based verification (not signed URLs) | KD-0260 D1 | Email verification uses token + expiry on the User model, matching the invite flow. Future verification flows should use the same pattern. |
| Pennant feature flags in central DB | KD-0286 ADR-001 | Features table is in central DB, scoped to Tenant model. Feature::for($tenant)->active(...) is the check pattern. |
| Client-side filtering is the default | KD-0276 D1 | Board/Backlog/Overview load all issues client-side and filter in memory. New filters should follow this pattern unless there's a specific server-side need. |
Integration Patterns
| Decision | Plan | Impact on Future Work |
|---|---|---|
| GitHub App token, not user OAuth | KD-0277 D3 | Agent tools always use GitHub App installation tokens. User OAuth tokens are only for the repo-linking flow. |
| OAuth Device Flow for CLI | KD-0237 D1 | Terminal-based auth uses RFC 8628 device flow. IDE extensions use Authorization Code + PKCE. |
| Socialite for login, GithubService for repos | KD-0341 D1 | Two separate GitHub OAuth apps with different scopes. Login uses Socialite, repo access uses custom GithubService. |
Decisions Under Active Discussion (Not Yet Accepted)
KD-0294 has 7 decisions all marked "Under discussion" — a notification retention and deletion research plan. Key open questions:
- Notification retention period (proposed 6 months)
- Hard delete vs soft delete (proposed hard delete)
- User-initiated deletion + system cleanup (proposed both)
- Scheduled cleanup command pattern
These are ready for implementation if the CEO approves.
3. Stalled vs Shipped — Completion Analysis
Methodology
A plan is completed if all tasks in TASKS.md are checked ([x]). Stalled means significant unchecked tasks remain with no recent activity. In progress means partially done with active work likely.
Completed Plans (54 of 73 with TASKS.md)
All tasks checked off in these plans:
| Plan | Domain | Tasks |
|---|---|---|
| IT-0072 (blocking issue nav) | UI | 4/4 |
| IT-0073 (assignee on create) | UI | 11/11 |
| IT-0095 (unassign button) | UI | 2/2 |
| IT-115 (2FA TOTP) | Security | 5/5 |
| IT-130 (multi-tenancy) | Architecture | 11/11 |
| KD-0101 (MCP blocking) | MCP | 3/3 |
| KD-0106 (MCP sprints) | MCP | 3/3 |
| KD-0113 (Mattermost adapter) | Integrations | 7/7 |
| KD-0115 (project action gating) | Permissions | 2/2 |
| KD-0116 (board action gating) | Permissions | 7/7 |
| KD-0117 (user management gating) | Permissions | 2/2 |
| KD-0161 (timelog refactor) | Time Tracking | 17/17 |
| KD-0163 (team edit search) | UI | 3/3 |
| KD-0166 (lane settings bugs) | UI | 4/4 |
| KD-0166 (MCP comment tools) | MCP | 2/2 |
| KD-0167 (MCP issue fields) | MCP | 1/1 |
| KD-0168 (MCP time/epic tools) | MCP | 2/2 |
| KD-0170 (member search) | UI | 4/4 |
| KD-0174 (expired invite notice) | Notifications | 3/3 |
| KD-0183 (multi-file upload) | Attachments | 5/5 |
| KD-0205-0208 (tenant CRUD) | Multi-Tenancy | 5/5 |
| KD-0244 (project leader) | Other | 3/3 |
| KD-0266 (project tokens) | Infrastructure | 5/5 |
| KD-0278 (sidebar membership) | UI | 4/4 |
| KD-0284 (task issue type) | UI | 3/3 |
| KD-0286 (feature flags) | Infrastructure | 13/13 |
| KD-0288 (mention notifications) | Notifications | 3/3 |
| KD-0293 (mark unread) | Notifications | 4/4 |
| KD-0305 (copy link issue key) | UI | 2/2 |
| KD-0324 (time entry filter) | Time Tracking | 2/2 |
| KD-0341 (OAuth login) | Authentication | 9/9 |
| claude-code-sdk-integration | Integrations | 8/8 |
| inbox-notifications | Notifications | 11/11 |
| it-0079 (filter persistence) | Other | 9/9 |
Plus ~20 more with all tasks checked.
Stalled / Abandoned Plans (12)
| Plan | Status | Tasks | Pattern |
|---|---|---|---|
| KD-0142 (frontend test improvement) | Stalled | 35/118 (30%) | Massive scope (118 tasks across all test files). Clearly too ambitious for a single plan. |
| KD-0283 | Stalled | 0/3 | Zero tasks completed. Browser tab title feature — may have been deprioritized. |
| tenancy-refactor-request-scoped | Stalled | 0/9 | Zero tasks completed. Request-scoped tenancy refactor — likely superseded by KD-0190. |
| KD-0125 (multi-project bot) | Stalled | 5/8 | 3 remaining tasks. Multi-project bot may have been overtaken by MCP evolution. |
| KD-0157 (feedback image upload) | Partial | 3/6 | Half done. May need to be revisited after KD-0349 (report attachments). |
In Progress (actively worked, some tasks remaining)
| Plan | Tasks | Notes |
|---|---|---|
| KD-0315 (CRUD permissions) | 18/19 | Nearly complete, 1 task remaining |
| KD-0320 (epic MCP tools) | 11/12 | Nearly complete |
| KD-0190 (multi-app architecture) | 14/15 | Nearly complete |
| KD-0343 (BYOK AI keys) | 8/9 | Nearly complete |
| KD-0292 (orphaned assignments) | 13/14 | Nearly complete |
Patterns in Completion
What gets finished:
- Plans with 3-15 tasks complete reliably. The sweet spot is 5-10 tasks.
- Plans with a clear single-PR scope (one feature, one domain) ship.
- Plans with DECISIONS.md tend to complete — the upfront decision-making prevents mid-stream confusion.
- MCP tool plans have a 100% completion rate (8/8). They're small, well-scoped, and follow established patterns.
What stalls:
- Plans with 100+ tasks (KD-0142 at 118 tasks is the extreme example). These should be split into multiple plans.
- Plans that overlap with later work (tenancy-refactor superseded by KD-0190, KD-0125 superseded by MCP evolution).
- Plans without PLAN.md or DECISIONS.md — pure TASKS.md-only plans from the early era are more likely to stall because there's no documented rationale for the approach.
4. Process Evolution — How Planning Format Changed Over Time
Era 1: Task Lists Only (IT-series, early KD-series)
Examples: IT-0072, IT-0073, IT-0095, KD-0101, KD-0106
Format:
- TASKS.md only, no PLAN.md or DECISIONS.md
- Tasks are detailed with Context blocks containing Why, Architecture, Key refs, Watch out
- Tasks include file paths, line numbers, and code patterns to follow
- RED/GREEN markers for test-first workflow
- Very prescriptive: tells the implementer exactly what to do
Strengths: Extremely detailed, no ambiguity for the engineer agent. Weaknesses: No high-level plan, no recorded decisions, no separation between "what" and "how."
Era 2: Plan + Tasks (mid KD-series)
Examples: IT-130, KD-0112, KD-0113, KD-0142, KD-0146, KD-0153
Format:
- PLAN.md appears alongside TASKS.md
- Plans have context, scope, and phased approach
- Tasks retain the detailed Context/Architecture/Key refs structure
- Some plans have extra artifacts (email-preview.blade.php for KD-0146, mockup.html for feature-planner)
Strengths: High-level rationale is now documented. Phases create natural work boundaries. Weaknesses: Decisions are implicit in the plan text, not structured for future reference.
Era 3: Plan + Decisions + Tasks (KD-0157 onward)
Examples: KD-0157, KD-0163, KD-0183, KD-0186, KD-0190
Format:
- DECISIONS.md as a separate artifact with structured format: Status, Context, Options considered, Decision, Consequences
- Plans reference decisions (e.g., "see D3")
- Multiple options are explicitly listed and evaluated
- Status tracking (Accepted, Superseded, Under discussion)
Strengths: Decisions are discoverable, referenceable, and auditable. Future agents can search DECISIONS.md to understand why something was built a certain way. Weaknesses: Early decision docs don't always have "Options considered" — some jump straight to the decision.
Era 4: Structured Plans with Key Design Decisions Table (KD-0315 onward)
Examples: KD-0315, KD-0341, KD-0343, KD-0349, KD-0355
Format:
- PLAN.md opens with metadata (Date, Status, Issue link, Decisions link)
- Key Design Decisions table — 5-10 row summary of major choices with rationale
- Scope section with explicit In scope / Out of scope lists
- DECISIONS.md has the full structured format (Context, Options, Decision, Consequences)
- Plans link to convention references (e.g., "Convention Reference" column in KD-0343 key decisions table)
- REVIEW.md and SIMPLIFY-REVIEW.md appear as post-implementation quality checks (KD-0315, KD-0260)
Strengths: The Key Design Decisions table lets the CEO review decisions at a glance without reading 23 full decision records. Convention references ensure the plan follows existing patterns. Post-implementation reviews catch issues before merge. Weaknesses: Plans can be quite long (KD-0315 has 6 plan variants). The convention reference pattern is new and not yet consistently applied.
Era 5: Multi-File Audit Plans (KD-0340)
Examples: KD-0340-permission-testing
Format:
- 16 files in a single plan directory, structured as a multi-phase audit
- Numbered phases (1-INVENTARISATIE, 2-VERGELIJKING, 3-GAPLIJST, etc.)
- Separate findings files per priority level
- TLDR summary for quick consumption
- DECISIONS.md records the fix strategy
Strengths: Thorough, systematic testing approach. Findings are traceable to test scenarios. Weaknesses: Very heavy process — only appropriate for security-critical audits.
Format Evolution Summary
| Element | Era 1 | Era 2 | Era 3 | Era 4 | Era 5 |
|---|---|---|---|---|---|
| TASKS.md | Detailed | Detailed | Detailed | Detailed | N/A |
| PLAN.md | No | Yes | Yes | Yes + metadata | Multi-file |
| DECISIONS.md | No | No | Yes (basic) | Yes (full format) | Yes |
| Key Decisions Table | No | No | No | Yes | No |
| In/Out of Scope | No | Implicit | Implicit | Explicit | Explicit |
| Convention References | No | No | No | Yes | No |
| Post-Review | No | No | No | Yes | N/A |
Implications for Kendo
What's Working Well
DECISIONS.md is the highest-value artifact. The 224+ decisions form a searchable knowledge base that prevents re-debating settled questions. Future agents can grep for "Avatar" or "MCP" and find the architectural rationale.
Small, focused plans ship. Every MCP tool plan completed. Every small UI fix completed. The engineering process excels at well-scoped work.
The permission system is remarkably well-documented. KD-0315 (23 decisions) + KD-0340 (8 decisions + full audit) + KD-0185 (3 decisions) = the most thoroughly documented subsystem in the product.
Convention references in plans (introduced in Era 4) prevent the planner from inventing patterns that already exist in the codebase. This is a significant improvement.
What Could Improve
Large plans need splitting discipline. KD-0142 (118 tasks) stalled at 30%. Plans over 15 tasks should be split into multiple issues, each with its own plan.
Stale plans create confusion.
tenancy-refactor-request-scoped(0/9 tasks) was likely superseded but never archived. A periodic cleanup or "archived" status would help.Dutch/English inconsistency. Early plans use Dutch for titles and task descriptions (IT-0073, KD-0097, KD-0153). Later plans use English. A single language (English, matching the codebase) would improve searchability.
Plans without PLAN.md or DECISIONS.md are harder to maintain. The 30+ plans that have only TASKS.md lack the context an engineer agent needs to make good decisions during implementation.
Open Questions
Should stale plans be archived? Plans like
tenancy-refactor-request-scopedandKD-0125-multi-project-botappear superseded. A formal archival process could reduce confusion.Is the KD-0294 notification retention research approved? Seven decisions are "Under discussion" — these seem ready for implementation but lack final approval.
What happened to KD-0142 (frontend test improvement)? At 35/118 tasks, this is the largest stalled plan. Was the approach abandoned, or is it being tackled incrementally through other plans?
Should DECISIONS.md be required for all plans? The correlation between having a DECISIONS.md and completing the plan is strong. Making it mandatory would be a low-cost process improvement.
Is the multi-agent pipeline (KD-0355) the future of AI features? It proposes replacing the dual quick/agent generation system with a 4-agent pipeline. If approved, it changes how every AI feature works going forward.
Related
- kendo-architectural-patterns.md — Synthesized patterns from the same DECISIONS.md files
- ../company/product-overview.md — Feature set these plans built
- ../company/marketing-strategy.md — Go-to-market context for prioritization