Agent Memento v0.2 — Complete Skill Specification

---
name: agent-memento
description: Tick-Driven Autonomous Production Factory for LLMs. A framework for long-running agents using Cron/Heartbeats and physical Markdown checklists to prevent OOM and context decay.
metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":["bash","openclaw"],"env":[]}}}
---

# Agent Memento v0.2 (Tick-Driven Autonomous Execution)

> "Don't build AI that tries to remember everything. Build systems that make AI read the blueprint anew every 5 minutes."

当我们在聊天框里让大模型"写一个游戏"时，开头总是美好的。但随着代码超过 2000 行，模型开始：
- **失忆症 (Amnesia)**：忘记了自己定义的接口，开始凭空捏造。
- **幻觉重构 (Hallucination)**：自信满满地输出一堆根本没有跑过的"完美"代码。
- **上下文核爆 (Resource Overload)**：为了修一个小 Bug，强行覆盖整个大文件，导致内存耗尽 (OOM)。

**核心原则：把"全知全能的超级 Agent"降级为无数个"只有 5 分钟记忆的、无情的 Tick 机器"。**

---


## Quick Start (30 秒上手)

1. 初始化项目：
   ```bash
   bash skills/agent-memento/scripts/init_memento.sh MyProject

2. 在主对话中让 Architect 填写 MASTER_PLAN.md 和 PROJECT_MAP.md
3. 启动自动执行：

   crontab -e
   # 添加：*/5 * * * * /path/to/MyProject/scripts/memento_tick.sh
   

4. （可选）启动 Dashboard 看板监控：

   bash scripts/dashboard.sh
   

5. 去刷手机。回来看 Dashboard 或 docs/TICK_STATUS.md 查看进度。

一、系统架构总览

┌─────────────────────────────────────────────────────────┐
│                    Human (You)                          │
│         Discord / 飞书 / Dashboard Panel                │
└──────────────┬──────────────────────────┬───────────────┘
               │ 自然语言交互              │ 面板批注/干预
               ▼                          ▼
┌─────────────────────────────────────────────────────────┐
│              Main Agent (Architect)                      │
│         LLM 本体 · 长对话 Session                        │
│                                                         │
│  职责：                                                  │
│  - 与人类讨论需求，翻译为结构化任务                         │
│  - 编辑 MASTER_PLAN.md（增/删/改/重排任务）                │
│  - 编辑 PROJECT_MAP.md（维护项目认知地图）                  │
│  - 读取 TICK_STATUS.md 和 Dashboard 批注                  │
│  - 根据反馈调整计划（自主决策 or 请示人类）                  │
└──────────────┬──────────────────────────────────────────┘
               │ 写入物理文件
               ▼
┌─────────────────────────────────────────────────────────┐
│              Physical State Layer (磁盘)                 │
│                                                         │
│  docs/MASTER_PLAN.md    ← 唯一真相源，结构化任务清单       │
│  docs/PROJECT_MAP.md    ← 项目认知地图 / 文件索引          │
│  docs/TICK_STATUS.md    ← Tick 执行状态流水账              │
│  docs/HUMAN_NOTES.md    ← 人类批注通道（面板写入）          │
│  logs/tick_*.log        ← 每个 Tick 的完整执行日志         │
└──────────────┬──────────────────────────────────────────┘
               │ 读取（每次从零开始）
               ▼
┌─────────────────────────────────────────────────────────┐
│           Tick Worker (Bricklayer)                       │
│      Cron 唤醒 · 短命进程 · 无状态 · 无情                 │
│                                                         │
│  生命周期：                                               │
│  1. 醒来 → 读 MASTER_PLAN.md                             │
│  2. 找到当前可执行任务                                     │
│  3. 读 PROJECT_MAP.md 确定上下文范围                       │
│  4. 读 HUMAN_NOTES.md 检查人类批注                        │
│  5. 执行任务 → 物理验证                                    │
│  6. 写结果到 TICK_STATUS.md                               │
│  7. 成功则标 [x]，失败则记录 → 死亡                        │
│  8. 自动 git commit                                      │
└─────────────────────────────────────────────────────────┘

二、The Methodology：三层智能分工

Layer 1：人类（方向盘）

• 在 Discord/飞书/Dashboard 中用自然语言描述需求和反馈
• 通过 Dashboard 面板随时插入批注、暂停/恢复流水线
• 不需要逐条审核——只在 Agent 请求帮助或自己想介入时参与

Layer 2：Architect（主 Agent / 翻译官）

• 与人类的主对话 Session
• 将模糊需求翻译为 MASTER_PLAN.md 中的结构化任务
• 持续维护 PROJECT_MAP.md（项目认知地图）
• 监控 TICK_STATUS.md，根据执行情况自主调整计划
• 遇到阻塞性决策时才请示人类

Layer 3：Tick Worker（子 Agent / 泥瓦匠）

• Cron 唤醒的短命进程，每次从零启动
• 绝对服从 MASTER_PLAN.md，不做创造性决策
• 执行 → 验证 → 汇报 → 死亡

三、物理状态文件规范

3.1 MASTER_PLAN.md — 唯一真相源

# MASTER_PLAN: \x3CProjectName>

## Meta
- created: 2025-01-15
- last_architect_edit: 2025-01-15T14:30:00
- tick_mode: auto          \x3C!-- auto | paused | stopped -->
- max_retries: 3           \x3C!-- 单任务最大重试次数 -->
- max_tasks_per_tick: 2    \x3C!-- 快任务时允许单 Tick 连续处理上限 -->
- max_diff_lines: 200      \x3C!-- diff size guard 阈值 -->
- stale_lock_timeout: 15min \x3C!-- [~] 僵尸锁重置阈值 -->
- circuit_breaker_threshold: 5 \x3C!-- 连续失败多少次触发熔断 -->
- clean_strategy: git-clean \x3C!-- 三阶段防爆清理机制 -->
- clean_ignore: .memento_cleanignore
- status_max_entries: 50    \x3C!-- TICK_STATUS.md 最大条目数，超出自动归档 -->
- status_archive_dir: logs/status_archive/
- total_ticks: 0           \x3C!-- 自动递增的 Tick 计数器 -->
- total_tasks: 15          \x3C!-- 自动维护 -->
- completed_tasks: 0       \x3C!-- 自动维护 -->

---

## Phase 1: Foundation
\x3C!-- parallel: true -->
\x3C!-- depends: none -->

- [ ] `T-101` [MODULE:database] Setup PostgreSQL schema
  - verify: `cd src && npm test -- --grep "db-schema" && echo PASS`
  - context_files: [src/db/schema.ts, src/db/migrations/]
  - guard_files: [src/auth/*]
  - estimate: 5min
  - retries: 0

- [ ] `T-102` [MODULE:auth] Implement JWT token generation
  - verify: `cd src && npm test -- --grep "jwt" && echo PASS`
  - context_files: [src/auth/jwt.ts, tests/auth/jwt.test.ts]
  - guard_files: [src/db/*]
  - estimate: 5min
  - retries: 0

## Phase 2: Integration
\x3C!-- parallel: false -->
\x3C!-- depends: Phase 1 -->

- [ ] `T-201` [MODULE:auth] Connect auth middleware to database
  - verify: `cd src && npm run test:integration && echo PASS`
  - context_files: [src/auth/middleware.ts, src/db/queries.ts]
  - guard_files: [src/db/schema.ts]
  - estimate: 10min
  - retries: 0

## Phase 3: Polish
\x3C!-- parallel: true -->
\x3C!-- depends: Phase 2 -->

- [ ] `T-301` [MODULE:docs] Generate API documentation
  - verify: `test -f docs/api.md && echo PASS`
  - context_files: [src/routes/*.ts]
  - guard_files: []
  - estimate: 3min
  - retries: 0

任务字段说明：

任务状态标记：

Phase 级元数据：

3.2 PROJECT_MAP.md — 项目认知地图

Worker 的 GPS。不读全部源码，先读地图，再按 context_files 精准加载。

# PROJECT MAP: \x3CProjectName>

## Architecture Overview
Single-page game using Canvas API. No framework. Vanilla TypeScript.

## Module Registry

### [MODULE:database]
- Purpose: PostgreSQL connection and schema management
- Entry: src/db/index.ts
- Key interfaces: `DbConnection`, `UserRecord`, `SessionRecord`
- Notes: Uses connection pooling via pg-pool

### [MODULE:auth]
- Purpose: JWT-based authentication
- Entry: src/auth/index.ts
- Key interfaces: `AuthToken`, `AuthMiddleware`
- Dependencies: [MODULE:database]
- Notes: Tokens expire in 24h, refresh flow not yet implemented

### [MODULE:routes]
- Purpose: Express route handlers
- Entry: src/routes/index.ts
- Dependencies: [MODULE:auth], [MODULE:database]

## File Tree (auto-maintained)
\x3C!-- Architect 应在项目结构变动时更新此区块 -->

src/
├── db/
│   ├── index.ts          # DB connection pool
│   ├── schema.ts         # Table definitions
│   └── migrations/       # SQL migration files
├── auth/
│   ├── index.ts          # Auth module entry
│   ├── jwt.ts            # Token generation/validation
│   └── middleware.ts      # Express middleware
└── routes/
    ├── index.ts          # Route registry
    └── users.ts          # User CRUD endpoints

## Conventions
- All tests in `tests/` mirror `src/` structure
- Config via environment variables (see .env.example)
- Error handling: all async handlers wrapped in try/catch, errors go to src/utils/errors.ts

维护规则：

• Architect 在创建/调整计划时同步更新
• Tick Worker 只读不写 PROJECT_MAP.md
• 如果 Worker 发现 MAP 与实际不符，在 TICK_STATUS.md 中报告，由 Architect 修正

3.3 TICK_STATUS.md — 执行状态流水账

# TICK STATUS LOG

---

## [2025-01-15T14:35:00] Tick #012
- **Task**: T-101 [MODULE:database] Setup PostgreSQL schema
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 2m18s
- **Files Modified**: src/db/schema.ts (+45 -0), src/db/migrations/001_init.sql (+23 -0)
- **Diff Size**: 68 lines
- **Git Commit**: `a3f7b2c` — "memento: complete T-101 database schema setup"

---

## [2025-01-15T14:35:00] Tick #012 (continued, tasks_this_tick: 2/2)
- **Task**: T-102 [MODULE:auth] Implement JWT token generation
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 3m41s
- **Files Modified**: src/auth/jwt.ts (+67 -0), tests/auth/jwt.test.ts (+34 -0)
- **Diff Size**: 101 lines
- **Git Commit**: `b8e2d1f` — "memento: complete T-102 JWT token generation"

---

## [2025-01-15T14:40:00] Tick #013
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: ❌ FAILED (retry 2/3)
- **Verify Output**: `TypeError: pool.query is not a function` (exit code 1)
- **Duration**: 4m52s
- **Error Analysis**: DB module exports `pool` but middleware imports `connection`. Interface mismatch.
- **Files Modified**: (rolled back)
- **Git Commit**: (none — rollback)

---

## [2025-01-15T14:45:00] Tick #014
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: 🚫 BLOCKED (retry 3/3 — max_retries exceeded)
- **Verify Output**: Same error as Tick #013
- **Error Analysis**: Recurring interface mismatch. Likely needs Architect to update MODULE:database exports or redefine task scope.
- **Escalation**: ⚠️ NEEDS ARCHITECT ATTENTION
- **Files Modified**: (rolled back)

---

3.4 HUMAN_NOTES.md — 人类批注通道

Dashboard 面板写入此文件。Tick Worker 每次启动时检查。Architect 也会读取。

# HUMAN NOTES

\x3C!-- 格式：每条批注带时间戳和目标（global / 具体 Task ID） -->
\x3C!-- Worker 执行完相关批注后，将 [NOTE] 改为 [NOTE:READ] -->
\x3C!-- Architect 处理完后可归档到底部的 Archive 区 -->

## Active Notes

### [NOTE] 2025-01-15T15:00:00 → T-201
改用 Redis 做 session 存储而不是 PostgreSQL。连接配置参考项目根目录的 redis.conf。

### [NOTE] 2025-01-15T15:10:00 → global
暂停 Phase 3 的所有任务，等 Phase 2 全部稳定再说。

### [NOTE:READ] 2025-01-15T14:00:00 → T-102
JWT secret 从环境变量 `JWT_SECRET` 读取，别硬编码。

---

## Archive
\x3C!-- Architect 把已处理的批注移到这里 -->

四、Tick 调度引擎规范

4.1 任务拾取算法

Tick Worker 醒来后执行以下逻辑：

1. 读取 MASTER_PLAN.md 的 Meta 区
   - 如果 tick_mode != "auto"，写一行 "Tick skipped: mode={mode}" 到 TICK_STATUS.md，退出

2. 读取 HUMAN_NOTES.md
   - 缓存所有 [NOTE]（非 [NOTE:READ]）条目，按 target 分组备用

3. 按 Phase 顺序扫描：
   FOR each Phase:
     a. 检查 depends 条件
        - 依赖的 Phase 内是否所有任务都是 [x] 或 [-]？
        - 如果有 [ ] 或 [~] 或 [!]，则该 Phase 不可进入，跳过
     
     b. 在当前 Phase 内扫描任务：
        - 跳过 [x] [!] [-] [~]
        - 对于 [ ]：检查 retries \x3C max_retries
        - 如果 parallel: false，只取第一个符合条件的 [ ]
        - 如果 parallel: true，取第一个符合条件的 [ ]（单 Worker 场景）
        
     c. 找到目标任务后，break

4. 如果没有找到任何可执行任务：
   - 检查是否所有任务都是 [x] 或 [-] → 写 "🎉 ALL TASKS COMPLETE" 到 TICK_STATUS.md
   - 检查是否存在 [!] 阻塞 → 写 "⚠️ PIPELINE BLOCKED" 到 TICK_STATUS.md
   - 退出

5. 将目标任务标记为 [~]（执行中）

6. 执行任务（详见 4.2）

7. tasks_completed_this_tick++
   如果 tasks_completed_this_tick \x3C max_tasks_per_tick 且剩余任务 estimate 合理：
     回到步骤 3 继续拾取
   否则退出

4.2 单任务执行流程

1. 读取任务的 context_files 列表
   - 通过 PROJECT_MAP.md 理解模块上下文
   - 加载 context_files 中声明的文件内容
   - 检查是否有针对该 Task ID 的 HUMAN_NOTES，如有，纳入上下文

2. 执行实际工作
   - 遵循铁血纪律（见第五节）
   - 生成精确 diff，不做全文件覆写

3. 运行 guard_files 检查
   - diff 中是否触及了 guard_files 列表中的文件？
   - 如果是 → 自动回滚 → 标记失败 → 原因写 "guard file violation"

4. 运行 diff size 检查
   - 单次修改是否超过 200 行？（可配置）
   - 如果是 → 自动回滚 → 标记失败 → 原因写 "diff too large, possible full-file rewrite"

5. 运行 verify 命令
   - 捕获 stdout/stderr 和 exit code
   - Exit Code 0 → SUCCESS
   - Exit Code != 0 → FAILED

6. 写结果到 TICK_STATUS.md

7. 如果 SUCCESS：
   - 任务标记 [ ] → [x]
   - retries 保持不变
   - git add + git commit（message 格式：`memento: complete {TASK_ID} {简述}`）

8. 如果 FAILED：
   - 回滚所有文件修改（git checkout 或备份恢复）
   - retries += 1
   - 任务保持 [ ]，清除 [~]
   - 如果 retries >= max_retries：
     - 标记 [!]
     - TICK_STATUS 中添加 "⚠️ NEEDS ARCHITECT ATTENTION"

4.3 并发安全

当 parallel Phase 中可能有多个 Worker 并行时（高级场景）：

• [~] 标记充当简易锁 —— Worker 拾取任务时先标 [~]，其他 Worker 看到 [~] 就跳过
• 如果检测到 [~] 标记超过 15 分钟未更新（Worker 可能崩溃），将其重置为 [ ]
• 在 MVP 阶段，建议单 Worker 串行执行，并发作为未来扩展

五、铁血纪律 (Execution Sandbox)

作为一个被 Memento 唤醒的 Tick Worker，你必须遵循：

纪律 1：防爆底线 (Surgical Edits Only)

• ❌ 严禁输出完整文件内容要求覆写
• ✅ 必须通过精准定位工具进行增量修改
• 硬约束：diff size guard 会物理阻断超大修改

纪律 2：拒绝脑内验算 (Evidence-Based Audit)

• ❌ 不许在脑中模拟运行然后宣称"应该没问题"
• ✅ 跑 verify 命令看真实退出码
• 没有 Exit Code 0，不许标 [x]

纪律 3：不要静默空转 (No Silent Ghosting)

• ❌ 遇到问题不许沉默退出
• ✅ 把死亡原因、错误日志、分析完整写入 TICK_STATUS.md
• 卡死了就大声喊出来，让 Architect 看到

纪律 4：恪守边界 (Stay in Your Lane)

• ❌ 不许修改 guard_files 中的文件
• ❌ 不许修改 MASTER_PLAN.md 的任务定义（只能改 checkbox 状态和 retries）
• ❌ 不许修改 PROJECT_MAP.md
• ✅ 只能读写 context_files 中声明的文件 + TICK_STATUS.md

纪律 5：原子提交 (Atomic Commits)

• 每完成一个任务，立即 git commit
• 每失败一个任务，立即 git checkout 回滚
• 确保任意时刻 git log 都是干净的、可追溯的

六、Dashboard 面板设计

6.1 设计理念

Dashboard 是人类与 Memento 流水线之间的异步交互界面。不是实时聊天，而是留言板 + 监控台。人类不需要一直盯着，但打开就能在 5 秒内知道一切。

6.2 面板布局

┌─────────────────────────────────────────────────────────────┐
│  🧠 Agent Memento Dashboard        [ProjectName]           │
│  Status: ● RUNNING    Uptime: 2h 35m    Next tick: 2m 14s  │
│  ┌──────────────────┐ ┌──────────────────────────────────┐  │
│  │ Controls         │ │ Progress                         │  │
│  │                  │ │                                  │  │
│  │ [▶ Resume]       │ │ ████████████░░░░░░░░░ 23/47     │  │
│  │ [⏸ Pause ]       │ │ Phase 1 ████████████ 100%       │  │
│  │ [⏹ Stop  ]       │ │ Phase 2 ████████░░░░  67%       │  │
│  │                  │ │ Phase 3 ░░░░░░░░░░░░   0%       │  │
│  │ Tick interval:   │ │                                  │  │
│  │ [5] min ▼        │ │ Blocked: 2 ⚠️                    │  │
│  │                  │ │ Est. remaining: ~1h 20m          │  │
│  └──────────────────┘ └──────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Task List                                    Filter: All │
│  │                                                          │
│  │  ✅ T-101 [database] Setup PostgreSQL schema    2m18s    │
│  │  ✅ T-102 [auth] JWT token generation           3m41s    │
│  │  🚫 T-201 [auth] Connect auth to DB            BLOCKED   │
│  │     └─ retries: 3/3 · "Interface mismatch"              │
│  │     └─ 💬 [Add Note]                                    │
│  │  ⬜ T-202 [auth] Password hashing              waiting   │
│  │  ⬜ T-301 [docs] Generate API docs             Phase 3   │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Tick Timeline                              Latest first  │
│  │                                                          │
│  │  14:45 Tick #014 · T-201 · 🚫 BLOCKED                  │
│  │  │  "Interface mismatch — needs Architect attention"     │
│  │  │  [View Full Log]                                      │
│  │  │                                                       │
│  │  14:40 Tick #013 · T-201 · ❌ FAILED (retry 2/3)        │
│  │  │  "TypeError: pool.query is not a function"            │
│  │  │  [View Full Log]                                      │
│  │  │                                                       │
│  │  14:35 Tick #012 · T-101 + T-102 · ✅✅                  │
│  │  │  2 tasks completed in 5m59s                           │
│  │  │  [View Full Log] [View Diff]                          │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ 📝 Notes                                                │
│  │                                                          │
│  │  ┌─────────────────────────────────────────────────────┐ │
│  │  │ Target: [T-201 ▼]  or  [global ▼]                  │ │
│  │  │                                                     │ │
│  │  │ 改用 Redis 做 session 存储，连接配置见 redis.conf    │ │
│  │  │                                                     │ │
│  │  │                              [Send Note 📤]         │ │
│  │  └─────────────────────────────────────────────────────┘ │
│  │                                                          │
│  │  Active Notes:                                           │
│  │  • 15:10 → global: "暂停 Phase 3..." ⏳ pending         │
│  │  • 15:00 → T-201: "改用 Redis..." ⏳ pending            │
│  │  • 14:00 → T-102: "JWT_SECRET 环境变量..." ✅ read      │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────┘

6.3 面板功能规范

控制区 (Controls)

进度区 (Progress)

• 数据源：解析 MASTER_PLAN.md 的所有 checkbox 状态
• 实时计算各 Phase 完成百分比
• 基于已完成任务的平均耗时 × 剩余任务数，估算剩余时间

任务列表 (Task List)

• 数据源：MASTER_PLAN.md
• 每个任务可展开查看：最近一次执行结果、错误信息、重试次数
• 支持过滤：All / Pending / Completed / Blocked
• 每个任务旁有 [Add Note] 按钮，快速针对该任务添加批注
• 支持手动操作：
  • 对 [!] 任务点击 [Reset Retries] → 将 retries 重置为 0，状态改回 [ ]
  • 对任务点击 [Skip] → 标记为 [-]

时间线 (Tick Timeline)

• 数据源：TICK_STATUS.md
• 倒序展示每个 Tick 的执行摘要
• 可展开查看完整日志（链接到 logs/tick_*.log）
• 可查看该 Tick 的 Git diff

批注区 (Notes)

• 写入目标：HUMAN_NOTES.md
• 支持选择 target（global 或具体 Task ID）
• 显示所有 Active Notes 及其状态（pending / read）
• Read 后的 notes 自动折叠但不删除

6.4 面板技术建议

• 轻量优先：纯静态页面 + 文件系统轮询（每 5~10s 读取 Markdown 文件）即可
• 数据层：直接 parse Markdown 文件，不需要数据库
• 可选方案 A：本地 HTTP server（Python/Node），serve 一个 SPA，通过 API 读写 Markdown 文件
• 可选方案 B：Terminal UI（blessed/ink），不离开终端

七、错误恢复与自愈机制

7.1 单任务失败 → 自动重试

失败 → retries++ → 保持 [ ] → 下个 Tick 重试
              ↓
       retries >= max_retries
              ↓
       标记 [!] → 写入 TICK_STATUS "NEEDS ARCHITECT ATTENTION"
              ↓
       跳过该任务，继续执行后续可执行任务

7.2 Phase 阻塞 → 智能跳转

Phase 2 中 T-201 被标记 [!]
              ↓
Phase 2 depends 未完全满足（存在非 [x]/[-] 的任务）
              ↓
Phase 3 无法启动
              ↓
如果 Phase 2 中还有其他 [ ] 任务 → 继续执行它们
如果 Phase 2 所有任务都是 [x]/[-]/[!] → 整条流水线 BLOCKED
              ↓
TICK_STATUS: "⚠️ PIPELINE BLOCKED — Phase 2 has unresolved [!] tasks"

7.3 Worker 崩溃 → 防腐检测

• 如果 [~] 标记存在超过 15 分钟（可配置），下一个 Tick Worker 将：
  • 重置该任务为 [ ]
  • 在 TICK_STATUS 中记录 "Stale [~] detected on {TASK_ID}, reset to [ ]"
  • 如果存在未提交的文件修改，执行 git checkout 清理

7.4 全局熔断

在以下情况下自动暂停流水线（tick_mode → paused）：

• 连续 5 个 Tick 全部失败（无一次 SUCCESS）
• 阻塞任务数超过总任务数的 30%
• 磁盘空间不足 / git 操作异常

在 TICK_STATUS 中写入：🔴 CIRCUIT BREAKER TRIGGERED — reason: {reason}

八、Architect 工作规范

当 Main Agent 处于 Architect 态时（与人类直接对话的 Session 中），遵循以下规范：

8.1 创建计划

1. 与人类讨论项目需求，理解全貌
2. 设计模块划分，写入 PROJECT_MAP.md
3. 将需求分解为原子任务，写入 MASTER_PLAN.md
4. 每个任务必须有 verify 命令 —— 没有验证命令的任务不配存在
5. 合理划分 Phase，声明 parallel 和 depends

8.2 监控与调整

1. 定期读取 TICK_STATUS.md（可由人类触发，或在对话中主动查看）
2. 对于 [!] 阻塞任务：
   • 分析失败原因
   • 修改任务定义（调整 verify、context_files、拆分子任务）
   • 或修改 PROJECT_MAP（更新接口定义）
   • 重置 retries 为 0，状态改回 [ ]
3. 对于 HUMAN_NOTES.md 中的批注：
   • 读取并理解
   • 将批注转化为 MASTER_PLAN 的具体修改
   • 处理完后归档

8.3 计划变更原则

• 新增任务：追加到合适的 Phase，保持 ID 唯一
• 删除任务：标记 [-] 并注释原因，不要真的删掉行
• 拆分任务：将原任务标记 [-] (拆分为 T-XXX, T-XXY)，新增子任务
• 重排 Phase：更新 depends 关系，确保 DAG 无环

九、初始化与部署

9.1 初始化命令

bash skills/agent-memento/scripts/init_memento.sh \x3CProjectName>

该脚本执行：

1. 在项目目录下创建 docs/ 目录
2. 生成 MASTER_PLAN.md 模板（含 Meta 区和示例 Phase）
3. 生成 PROJECT_MAP.md 模板
4. 生成 TICK_STATUS.md（空）
5. 生成 HUMAN_NOTES.md（空）
6. 创建 logs/ 目录
7. 生成 scripts/memento_tick.sh —— Tick Worker 的入口脚本
8. 生成 .memento_ignore（排除 node_modules/, .git/, logs/ 等）
9. 生成 scripts/tick_worker_system_prompt.md —— 注入给 Worker 的全套纪律法则和 Output 规范。
10. 生成 .memento_cleanignore（保护 node_modules/, .env, vendor/ 等）
11. 输出提示：“请将以下行添加到 crontab 以启动自动执行”

9.1.1 Tick Worker System Prompt 模板 (tick_worker_system_prompt.md)

以下是 init_memento.sh 应生成的 scripts/tick_worker_system_prompt.md 的完整内容：

# Memento Tick Worker — System Prompt

You are a Memento Tick Worker: a short-lived, stateless, disciplined execution agent.
You have no memory of previous ticks. You start fresh every time.

## Your Lifecycle (execute in this exact order)

1. Read `docs/MASTER_PLAN.md`. Parse the Meta section for configuration.
2. Read `docs/HUMAN_NOTES.md`. Note any `[NOTE]` entries (ignore `[NOTE:READ]`).
3. Scan Phases in order. For each Phase:
   - Check `depends`: all tasks in depended Phase must be `[x]` or `[-]`.
   - Find the first task marked `[ ]` with `retries \x3C max_retries`.
4. If no executable task found:
   - If all tasks are `[x]`/`[-]`: write "🎉 ALL TASKS COMPLETE" to TICK_STATUS.md.
   - If any `[!]` exists: write "⚠️ PIPELINE BLOCKED" to TICK_STATUS.md.
   - Exit.
5. Mark the target task `[~]` in MASTER_PLAN.md.
6. Read `docs/PROJECT_MAP.md` for module context.
7. Load ONLY the files listed in the task's `context_files`.
8. If there are `[NOTE]` entries targeting this task ID or `global`, incorporate them.
9. Perform the work using surgical, targeted edits. NEVER output a full file.
10. Verify:
    - Check: did you modify any file listed in `guard_files`? If yes → rollback → fail.
    - Check: is your total diff > `max_diff_lines`? If yes → rollback → fail.
    - Run the task's `verify` command. Capture exit code, stdout, stderr.
11. Write a TICK_STATUS.md entry (format below).
12. If verify exit code == 0:
    - Mark task `[x]`. Run `git add -A && git commit -m "memento: complete {TASK_ID} {description}"`.
    - If `tasks_completed_this_tick \x3C max_tasks_per_tick`, go to step 3 for next task.
13. If verify exit code != 0:
    - Rollback: `git checkout -- .`
    - Increment `retries` in MASTER_PLAN.md.
    - If `retries >= max_retries`: mark task `[!]`, add "⚠️ NEEDS ARCHITECT ATTENTION" to status.
    - Clear `[~]` back to `[ ]` (or `[!]`).
14. Exit.

## TICK_STATUS.md Entry Format

## [{timestamp}] Tick #{tick_number}
- **Task**: {TASK_ID} [MODULE:{module}] {description}
- **Status**: ✅ SUCCESS | ❌ FAILED (retry {n}/{max}) | 🚫 BLOCKED
- **Verify Output**: {first 5 lines of stdout/stderr} (exit code {n})
- **Duration**: {time}
- **Error Analysis**: {your diagnosis of what went wrong — FAILED/BLOCKED only}
- **Files Modified**: {file (+lines -lines)} | (rolled back)
- **Diff Size**: {total lines changed}
- **Git Commit**: {hash} — "{message}" | (none — rollback)
- **Outputs**: {key interfaces/exports created — SUCCESS only, optional but encouraged}

## Iron Disciplines (violation = immediate failure)

1. **SURGICAL EDITS ONLY**: Never output a complete file. Use precise, targeted modifications.
2. **EVIDENCE-BASED**: Run `verify`. No exit code 0 = no `[x]`. No exceptions.
3. **NO SILENT GHOSTING**: If stuck, write full error + analysis to TICK_STATUS.md. Never exit silently.
4. **STAY IN YOUR LANE**: Only modify files in `context_files`. Never touch `guard_files`. Never edit task definitions in MASTER_PLAN.md (only checkbox state + retries). Never edit PROJECT_MAP.md.
5. **ATOMIC COMMITS**: `git commit` on success. `git checkout` on failure. Always.

## What You Are NOT

- You are NOT an architect. Do not redesign, re-plan, or question the task definition.
- You are NOT creative. Execute exactly what is specified.
- You are NOT persistent. After this tick, you will cease to exist.

9.2 Tick 入口脚本模板 (memento_tick.sh)

#!/usr/bin/env bash
set -euo pipefail

PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PLAN="$PROJECT_DIR/docs/MASTER_PLAN.md"
STATUS="$PROJECT_DIR/docs/TICK_STATUS.md"
LOG_DIR="$PROJECT_DIR/logs"
TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S)
TICK_LOG="$LOG_DIR/tick_${TIMESTAMP}.log"

# 防撞车：确保同一时间只有一个 Tick Worker 运行
LOCK_FILE="$PROJECT_DIR/.memento.lock"
exec 200>"$LOCK_FILE"
if ! flock -n 200; then
  echo "[$TIMESTAMP] Tick skipped: previous tick still running" >> "$STATUS"
  exit 0
fi

# 检查 tick_mode
TICK_MODE=$(grep -oP 'tick_mode:\s*\K\w+' "$PLAN" || echo "stopped")
if [[ "$TICK_MODE" != "auto" ]]; then
  echo "[$TIMESTAMP] Tick skipped: mode=$TICK_MODE" >> "$STATUS"
  exit 0
fi

# 调用 LLM Agent 执行 Tick
SYSTEM_PROMPT="$(cat "$PROJECT_DIR/scripts/tick_worker_system_prompt.md")"

openclaw agent \
  --system-prompt "$SYSTEM_PROMPT" \
  --prompt "Read $PLAN, find the first executable task, complete it following the Memento Tick Worker protocol. Write results to $STATUS." \
  --context-files "$PLAN" "$PROJECT_DIR/docs/PROJECT_MAP.md" "$PROJECT_DIR/docs/HUMAN_NOTES.md" \
  2>&1 | tee "$TICK_LOG"

# 后处理：三阶段防爆清理
cd "$PROJECT_DIR"
if [[ -n $(git status --porcelain) ]]; then
  echo "[$TIMESTAMP] WARNING: Dirty workspace detected. Running 3-phase cleanup." >> "$STATUS"

  # Phase 1: 恢复已追踪文件
  git checkout -- .

  # Phase 2: 清理未追踪文件（排除保护列表）
  if [[ -f ".memento_cleanignore" ]]; then
    git clean -fd --exclude-from=.memento_cleanignore
  else
    git clean -fd
  fi

  # Phase 3: 兜底——如果还是脏的，紧急 stash
  if [[ -n $(git status --porcelain) ]]; then
    git stash --include-untracked -m "memento-emergency-stash-$TIMESTAMP"
    echo "[$TIMESTAMP] CRITICAL: Emergency stash created. Manual inspection required." >> "$STATUS"
  fi
fi

# 日志轮转
MAX_ENTRIES=$(grep -oP 'status_max_entries:\s*\K\d+' "$PLAN" || echo "50")
CURRENT_ENTRIES=$(grep -c '^\## \[' "$STATUS" || true)
if [[ $CURRENT_ENTRIES -gt $MAX_ENTRIES ]]; then
  ARCHIVE_DIR="$PROJECT_DIR/logs/status_archive"
  mkdir -p "$ARCHIVE_DIR"
  mv "$STATUS" "$ARCHIVE_DIR/TICK_STATUS_$(date +%Y%m%d_%H%M%S).md"
  echo "# TICK STATUS LOG" > "$STATUS"
  echo "" >> "$STATUS"
  echo "\x3C!-- Rotated at $TIMESTAMP. Previous entries archived. -->" >> "$STATUS"
fi

# 告警检测
BLOCKED_COUNT=$(grep -c '\[!\]' "$PLAN" || true)
CIRCUIT_BROKEN=$(grep -c 'CIRCUIT BREAKER' "$STATUS" || true)

if [[ $BLOCKED_COUNT -gt 0 || $CIRCUIT_BROKEN -gt 0 ]]; then
  cat > "$PROJECT_DIR/.memento_alert" \x3C\x3C EOF_INNER
timestamp: $TIMESTAMP
blocked_tasks: $BLOCKED_COUNT
circuit_breaker: $([[ $CIRCUIT_BROKEN -gt 0 ]] && echo "TRIGGERED" || echo "OK")
message: Pipeline needs attention. $BLOCKED_COUNT task(s) blocked.
EOF_INNER
fi

# 如果一切正常且之前有告警，清除告警
if [[ $BLOCKED_COUNT -eq 0 && $CIRCUIT_BROKEN -eq 0 && -f "$PROJECT_DIR/.memento_alert" ]]; then
  rm -f "$PROJECT_DIR/.memento_alert"
fi

9.3 Cron 配置

# 每 5 分钟执行一次
*/5 * * * * /path/to/project/scripts/memento_tick.sh >> /path/to/project/logs/cron.log 2>&1

十、完整工作流示例

人类："我想做一个带用户系统的 REST API"
  │
  ▼
Architect（主 Session）：
  ├─ 与人类讨论确认：PostgreSQL + JWT + Express
  ├─ 写入 PROJECT_MAP.md（模块划分）
  ├─ 写入 MASTER_PLAN.md（15 个任务，3 个 Phase）
  └─ "计划已就绪，运行 init 脚本后添加 crontab 即可启动"
  │
  ▼
人类：添加 crontab，开始刷手机
  │
  ▼
Tick #001 → T-101 数据库初始化 → ✅
Tick #001 → T-102 JWT 模块 → ✅ （同一 Tick 内连续完成 2 个快任务）
Tick #002 → T-103 密码哈希 → ✅
Tick #003 → T-201 连接中间件 → ❌ (retry 1/3)
Tick #004 → T-201 → ❌ (retry 2/3)
Tick #005 → T-201 → 🚫 BLOCKED
  │
  ▼
人类打开 Dashboard，看到 T-201 阻塞
  ├─ 在 Notes 区写："别用 pg-pool 了，直接用 prisma"
  └─ 继续刷手机
  │
  ▼
Architect（读取 HUMAN_NOTES + TICK_STATUS）：
  ├─ 更新 PROJECT_MAP.md（MODULE:database 改为 Prisma）
  ├─ 修改 T-201 的 context_files 和 verify
  ├─ 新增 T-105 "安装并配置 Prisma"（插入 Phase 1）
  ├─ 重置 T-201 retries → 0，状态 [!] → [ ]
  └─ 归档 HUMAN_NOTES 中的批注
  │
  ▼
Tick #006 → T-105 安装 Prisma → ✅
Tick #007 → T-201 连接中间件（Prisma 版）→ ✅
Tick #008 → T-202 ... → ✅
  │
  ... 持续推进 ...
  │
  ▼
Tick #031 → 🎉 ALL TASKS COMPLETE
  │
  ▼
人类打开 Dashboard："哦，做完了。" 移除 crontab。

Security & Transparency

Data Access — Exactly What Is Read

• Reads \x3Cproject-dir>/docs/MASTER_PLAN.md to determine the current task
• Reads \x3Cproject-dir>/docs/PROJECT_MAP.md for project structure awareness
• Reads \x3Cproject-dir>/docs/HUMAN_NOTES.md for human annotations
• Reads source code files listed in each task's context_files only

Data Written

• Creates project scaffolding (MASTER_PLAN.md, PROJECT_MAP.md, TICK_STATUS.md, HUMAN_NOTES.md, memento_tick.sh)
• Updates checkbox states in MASTER_PLAN.md (Tick Worker: only [ ]↔[x]/[!]/[~])
• Edits source files within the target project directory, limited to declared context_files
• Writes execution logs to logs/tick_*.log
• Creates git commits for successful task completions

Hard Safety Guards

• Diff size limit: Rejects changes > 200 lines per task (configurable)
• Guard files: Physically prevents modification of declared protected files
• Auto-rollback: Failed tasks are rolled back via git checkout
• Circuit breaker: Auto-pauses pipeline on sustained failures

Persistence & Autonomous Scheduling

• The init_memento.sh script generates a bash script intended to be run via cron
• The user must manually add this to their crontab to enable autonomous execution
• Stop at any time by removing the crontab entry or setting tick_mode: stopped

Credentials

• Operates entirely locally
• Relies on openclaw agent with the system's existing LLM configurations
• No new keys are requested or stored

Network Access

• No outbound network access by framework scripts
• Network access may occur only when user-defined verify commands require it (e.g., npm install)

---

## 附录：文件结构总览

\x3Cproject>/ ├── docs/ │ ├── MASTER_PLAN.md # 唯一真相源 │ ├── PROJECT_MAP.md # 项目认知地图 │ ├── TICK_STATUS.md # 执行状态流水账 │ └── HUMAN_NOTES.md # 人类批注通道 ├── logs/ │ ├── cron.log # cron 调度日志 │ ├── tick_2025-01-15T14:35:00.log │ └── tick_2025-01-15T14:40:00.log ├── scripts/ │ └── memento_tick.sh # Tick Worker 入口 ├── .memento_ignore # 上下文排除规则 └── src/ # 实际项目代码 └── ...