RFC: establish repository and documentation ownership boundaries

[Astro-Han]

Summary

Maka now has three intended product surfaces—Desktop, TUI, and Headless—but its repository and documentation ownership have not evolved at the same pace.

This RFC proposes two related changes:

1. clarify the boundary between products, shared packages, benchmarks, and generated state;
2. define where stable documentation, local architecture, and time-sensitive plans belong.

The goal is not a repository-wide rewrite. It is to make ownership discoverable and prevent documentation and directory structure from drifting again.

Current problems

Documentation authority is unclear

Root and package READMEs, architecture contracts, implementation plans, research notes, issues, and PRs overlap.

This creates several failure modes:

• readers cannot tell which document is authoritative;
• time-sensitive progress is copied into long-lived documentation and becomes stale;
• duplicate or superseded documents remain discoverable as if current;
• package architecture exists in code or contributor knowledge but not near the package;
• README content drifts from current exports, paths, scripts, and behavior.

This RFC continues the direction established by #725 and recent documentation work from @jackwener and @likun666661.

Repository ownership is unclear

The existing package dependency boundaries are generally sound, but the repository does not consistently distinguish:

• product entry points from shared packages;
• reusable headless mechanisms from benchmarks and experiments;
• benchmark source from generated runs;
• active design contracts from completed implementation plans.

Principles

• Existing code and contract tests remain the final authority.
• A package or directory must represent a real product, dependency, runtime, or ownership boundary.
• Directory symmetry alone is not a reason to move code.
• Stable direction belongs in documentation; time-sensitive progress belongs in issues and PRs.
• Replaced paths should be removed rather than retained in parallel.
• New abstractions should follow demonstrated consumers and constraints, not anticipated ones.
• Each migration step must be independently verifiable and revertible.

Proposed ownership model

Documentation

Location	Responsibility
Root README.md	Stable product overview, quick start, and repository navigation
Package/module README.md	Local architecture, public seams, ownership, and where new code belongs
docs/	Authoritative cross-cutting architecture, security, privacy, product, and validation contracts
Issues and PRs	Plans, migration progress, implementation rounds, and TODOs
Source and contract tests	Final authority when documentation and implementation disagree

Add:

docs/README.md
docs/archive/

docs/README.md should identify current contracts, active proposals, local architecture READMEs, research, and historical material.

Completed plans should move to docs/archive/. Verified duplicate documents should be removed after references are updated.

Do not pre-create a large documentation hierarchy. Topic directories should appear only after a real document cluster exists.

Repository

Use the following minimal target shape:

apps/
 desktop/
 tui/ # moved from packages/cli

packages/
 core/
 storage/
 runtime/
 headless/
 src/
 harbor/
 ui/

benchmarks/
 terminal-bench/ # independent benchmark source

docs/
 README.md
 archive/
 <current documents remain mostly flat>

scripts/

.local/ # ignored generated runs and artifacts

This is an ownership map, not a requirement to create empty directories.

Proposed changes

1. Move the interactive terminal product to apps/tui

Move:

packages/cli/

to:

apps/tui/

“TUI” describes the product more accurately and distinguishes it from the headless CLI.

Keep the existing package behavior and user-facing binaries:

maka
maka-agent

This is a Maka-specific semantic decision, not a universal rule that executables must live under apps/.

2. Retain the existing shared package boundaries

Keep:

packages/core/
packages/storage/
packages/runtime/
packages/headless/
packages/ui/

These packages currently enforce useful dependency or runtime boundaries.

Do not introduce packages/harness yet. Reconsider it when @maka/headless has another stable product consumer, a distinct deployment lifecycle, or a demonstrated dependency problem.

Do not rename @maka/core yet. Move incorrectly owned files incrementally when their destination is clear.

3. Separate benchmark source from generated state

Use:

benchmarks/ # independent runners, tasks, fixtures, configs
packages/headless/ # reusable mechanisms and supported adapters
.local/ # runs, logs, jobs, artifacts

Move independent Terminal-Bench assets under benchmarks/.

Keep packages/headless/harbor/maka_agent.py as the single Harbor adapter. Harbor, AHE, prompt optimization, and RSI code should move only after their ownership and public API boundaries are clear.

4. Keep cloud deployment as a Headless roadmap constraint

Headless should remain compatible with server and restricted-container execution.

Do not create apps/server until persistent service responsibilities such as remote APIs, scheduling, tenancy, or service-level credential management exist.

Open decisions

Test ownership

Which convention should Maka adopt?

• tests colocated with source;
• package-level test/ mirroring source;
• the current src/__tests__/ layout.

The decision should consider ownership, navigation, integration-test boundaries, and migration cost. No repository-wide test move should happen before agreement.

Package-internal directories

When should a flat file cluster become a directory?

The decision should be based on stable responsibility, ownership, change coupling, or a useful public entry point—not a fixed file count.

Potential candidates include goals, compaction, subscriptions, sessions, and tools.

Headless versus Harness

What evidence should trigger splitting:

apps/headless/
packages/harness/

from the current packages/headless package?

Benchmark ownership

Which evaluation code is an independent benchmark, and which remains part of the supported Headless implementation?

Documentation freshness

Which safeguards are worth maintaining?

• internal link and referenced-path checks;
• validation of documented exports and scripts;
• status markers for ambiguous documents;
• package README coverage;
• an explicit freshness owner.

The safeguard must cost less to maintain than the drift it prevents.

Rollout

Phase 1: documentation authority

• Add docs/README.md.
• Audit current documents.
• Archive completed plans.
• Remove verified duplicates.
• Link package architecture READMEs from the index.
• Add only lightweight freshness checks with demonstrated value.

Phase 2: repository classification

• Establish .local/ for generated state.
• Move packages/cli to apps/tui.
• Move independent Terminal-Bench assets under benchmarks/.

Phase 3: incremental ownership cleanup

• Resolve Headless and benchmark ownership before moving coupled code.
• Move incorrectly owned core files only when their destination is clear.
• Reorganize package-internal domains when those areas are materially changed.
• Apply the agreed test convention to new or restructured modules.

Non-goals

• Runtime behavior or storage format changes
• User-facing binary renames
• A repository-wide source or test migration
• Empty apps/server or packages/harness scaffolding
• Parallel old and new module paths
• Moving files solely for visual symmetry
• Copying another repository’s layout mechanically

References

Related Maka work:

• docs(frontend): add architecture READMEs for ui, renderer, and desktop #725
• docs: convergence map — campaign complete #705
• roadmap: durable agent platform #544
• packages/ui/README.md
• apps/desktop/README.md
• apps/desktop/src/renderer/README.md
• docs/runtime-kernel.md
• docs/runtime-v2-architecture-evolution.md

Repository comparisons:

• Codex
• Gemini CLI
• OpenCode
• Pi
• Hermes Agent
• Raven

These projects use different layouts. This RFC therefore treats real ownership and dependency constraints—not directory convention—as the authority.