README.md

Molibot Docs

This directory is organized by document purpose first, then by topic. Start with the feature overview when you want to understand what Molibot can do today.

docs/agent-dev-series/ and docs/superpowers/ are maintained as standalone collections and keep their existing internal structure.

Archived material lives under archive/: quarterly root-record archives (prd-archive-YYYY-QN.md, features-archive-YYYY-QN.md, changelog-YYYY-QN.md) plus subdirectories for superseded/delivered standalone documents (archive/requirements/, archive/designs/, archive/guides/). Archived content is frozen history, not authority for current behavior.

Directory map

Directory	Use for
features/	User-facing capability explanations, starting points, and current boundaries.
guides/	Operator and developer guides for using, configuring, deploying, and extending Molibot.
requirements/	Planned product scope, MVP boundaries, and acceptance-oriented requirements.
adr/	Accepted architecture decisions and the reasoning behind them, for decisions that outlive any one feature.
designs/	Durable architecture, technical designs, and system proposals.
research/	External research, market notes, competitor analysis, and background investigation.
reviews/	Durable technical review conclusions and post-analysis reports.
work/	Time-bound implementation plans, handoffs, progress trackers, implementation-linked reviews, and audit evidence. Not a stable product-documentation entrypoint.
reference/	Raw provider documentation, prompt captures, API examples, and other source material.
articles/	Long-form publishable articles and drafts.
images/	Shared diagrams and image assets.
archive/	Historical changelog, feature, and PRD records.
agent-dev-series/	Agent development article series.
superpowers/	Superpowers planning, specification, and review documents.

开发与界面规范

• 开发与验证指南：实现、修复、持久化、定向验证与记录维护。
• 设计规范：视觉与交互核心约定，含主题、布局、动效和页面专项入口。
• Pitfalls：按模块分类的事故索引与完整复盘。

Common entrypoints

Features

• Personal Agent and Memory
• Channels and Surfaces
• Tools, Skills, and MCP
• Automation, Approvals, and Sandbox
• Scheduled Task Execution and Recovery
• Desktop Project Workspace

Planned and requirements

• Assistant Capability Matrix — the single four-state current-status source
• Personal Agent 工作首页 UI — 已确认的日报、选题、审批与执行概览布局；包含参考图、数据接线与定向验收，待实施
• Personal Agent：授权事项的持续跟进与交付 — 三阶段产品草案：项目跟进、个性化、外部来源与受控执行；Phase One 实施 Spec
• Large Autonomous Execution PRD — proposed continuous execution, dynamic decomposition and large-batch acceptance
• Automatic Durable Execution PRD — long-task foundation, partially delivered
• Pi capabilities integration spec — phased Durable kernel replacement, Deferred responses, Codemode and optional image backend
• Pi capability completion spec — approved ordinary-task recovery, MCP OAuth, Codemode model API and extension runtime interfaces; Issue #64
• Durable wakeup queue and executor hardening — SQLite 唤醒队列、事务内入队、租约与错误分级；technical design
• Permission Modes PRD — Plan/Manual/Accept/Auto session scope
• Feature verification automation — isolated instance, scripted model, verify:feature, and the UI/native coverage manifest
• Project Automations PRD — Project-scoped periodic Runtime Tasks
• Artifact Panel PRD — shared artifact registry and inspection
• Plugin-owned Settings PRD — plugin contract reference migration
• Mini App Platform Roadmap — platform extension direction
• Multi-Agent Room Spec — long-lived Desktop conversations with configured Agent participants
• OpenConnector plan — third-party integration gateway
• Realtime avatar conversation plan — draft proposal, not scheduled

Architecture and operation

• Architecture decisions (ADR)
• Pi runtime upgrade and rollback — 1.4 compatibility, execution database backups and service cutover
• Pi Codemode integration validation — shared authorization, approval continuation, execution isolation and input measurement
• pi-mono upgrade assessment
• Market positioning research
• V1 architecture (archived)
• Agent redesign (earlier revisions archived: v2.0, v2.1)
• Agent runtime designs — execution flow, event timeout/retry, approval convergence
• Durable wakeup queue and runtime hardening spec — SQLite 唤醒队列、事务内入队、heartbeat/CAS 硬化与 pi-durable 对照
• Memory design
• Channel message architecture
• Prompt designs
• Sandbox research — subagent sandbox, sandbox approval optimization
• Research — memory systems, market positioning, Hermes/OpenClaw notes
• Sandbox designs
• Plugin guides — manifest design, plugin contract, plugin authoring
• Pi extension server runtime — supported methods, ownership, cancellation and model-call limits
• Subagent execution and failure recovery
• Deferred tool guide
• Permission modes × sandbox policy
• Call trace guide · Trace design
• Operations / remote control

Filing rules

• Put new stable documentation in the directory that matches its current purpose, not only its feature area.
• Put explanations of shipped, user-visible behavior in features/; link from those pages to relevant guides and durable designs.
• Put time-bound execution plans, handoffs, progress trackers, screenshot audits, and implementation-linked review material in work/.
• If a process document becomes a durable decision, extract or move the durable conclusion to requirements/, designs/, reviews/, or features.md; do not make work/ a dependency for normal use.
• If a document changes purpose, move it instead of duplicating it.
• Keep raw API examples and copied prompt/provider material under reference/.
• Keep publishable prose under articles/.
• Keep the repository's domain glossary under reference/CONTEXT.md.
• Keep the current capability status only in requirements/personal-assistant-capability-matrix.md; plan/PRD/design documents under requirements/ and designs/ must stay current with shipped reality or be archived via the doc-lifecycle rules.