按 artifact 类型+ID

一、全局概览

作用域

核心原则

• .workflow/ 加入 .gitignore，不进版本控制（project.md 可选例外）
• 所有产物路径相对于 .workflow/ 根目录
• 每个目录/文件职责单一，不交叉存储
• 所有命令输出通过 state.json.artifacts[] 统一注册，支持跨阶段追踪

二、目录树

.workflow/
├── state.json                    # 项目状态机 + Artifact Registry
├── config.json                   # 用户工作流配置
├── project.md                    # 项目定义（Core Value, Requirements, Key Decisions）
├── roadmap.md                    # 里程碑/阶段路线图
├── wiki-index.json               # Wiki 统一索引（WikiIndexer 自动生成）
├── search-cache.json             # Wiki 搜索缓存（BM25F 索引 + mtime 快照）
├── search-daemon.json            # 搜索守护进程状态（pid/port/startedAt）
├── embedding-index.bin           # 向量嵌入索引（ONNX 模型生成）
├── spec-analytics.jsonl          # Spec 注入分析日志
│
├── specs/                        # 规范文件（6 类，项目级）
│   ├── coding-conventions.md     # 编码规范（核心）
│   ├── architecture-constraints.md # 架构约束（核心）
│   ├── knowhow.md                # 知识索引（核心）
│   ├── quality-rules.md          # 质量规则（可选）
│   ├── test-conventions.md       # 测试规范（可选）
│   ├── debug-notes.md            # 调试笔记（可选）
│   ├── review-standards.md       # 审查标准（可选）
│   └── learnings.md              # 学习记录（可选）
│
├── knowhow/                      # 知识文档（9 种前缀 + learn 特殊前缀）
│   ├── .maestro-learn/           # maestro-learn 会话状态
│   ├── KNW-*.md                  # session
│   ├── TIP-*.md                  # tip
│   ├── TPL-*.md                  # template
│   ├── RCP-*.md                  # recipe
│   ├── REF-*.md                  # reference
│   ├── DCS-*.md                  # decision
│   ├── AST-*.md                  # asset
│   ├── BLP-*.md                  # blueprint
│   ├── DOC-*.md                  # document
│   ├── KNW-follow-*.md           # maestro-learn follow
│   ├── KNW-decompose-*.md        # maestro-learn decompose
│   ├── KNW-retro-*.md/json       # retrospective 步骤
│   ├── KNW-opinion-*.md          # maestro-learn consult
│   ├── KNW-investigate-*/        # maestro-learn investigate
│   ├── KNW-digest-*.md           # wiki-digest
│   └── wiki-connections-*.md     # wiki-connect
│
├── scratch/                      # 执行产物（{YYYYMMDD}-{type}[-P{N}]-{slug}）
│   ├── *-analyze-*/              # 分析：discussion.md, analysis.md, conclusions.json, context.md, context-package.json
│   ├── *-plan-*/                 # 规划：plan.json, .task/TASK-*.json
│   │   └── .summaries/           # 执行：TASK-{NNN}-summary.md
│   ├── *-verify-*/               # 验证：verification.json
│   ├── *-review-*/               # 审查：review.json
│   ├── *-debug-*/                # 调试：understanding.md, evidence.ndjson
│   ├── *-test-*/                 # 测试：uat.md, test-results.json, coverage-report.json
│   ├── *-auto-test-*/            # 自动测试：report.json
│   ├── *-brainstorm-*/           # 头脑风暴：guidance-specification.md, {role}/, context-package.json
│   ├── *-collab-*/               # 协作：collab-report.md, context.md, context-package.json, per-tool/
│   ├── *-import-*/               # 外部文档导入：source.{ext}, context-package.json
│   └── *-ui-design-*/            # UI 设计：MASTER.md, design-tokens.json
│
├── issues/                       # 问题追踪
│   ├── issues.jsonl              # 活跃问题
│   ├── issue-history.jsonl       # 归档问题
│   └── discoveries/              # 发现会话
│
├── milestones/                   # 里程碑归档
│   └── {M}/
│       ├── artifacts/            # 归档产物
│       ├── audit-report.md
│       ├── summary.md
│       └── roadmap-snapshot.md
│
├── codebase/                     # 代码库文档（mapper agent 生成）
│   ├── doc-index.json
│   ├── tech-stack.md
│   ├── architecture.md
│   ├── features.md
│   └── concerns.md
│
├── active/                       # WFS 工作流会话
│   └── WFS-{name}-{date}/        # 活跃工作流会话
│
├── explore/                      # Explore 会话存储
│   └── exp-{date}-{id}.json      # 探索会话结果
│
├── domain/                       # 领域知识系统
│   ├── glossary.yaml             # 术语表（YAML 格式，主格式）
│   ├── glossary.json             # 术语表（JSON 格式，向后兼容）
│   └── concepts/                 # 概念文档
│
├── kg/                           # 知识图谱数据库
│   └── maestro.db                # SQLite 数据库（MaestroGraph）
│
├── learning/                     # 学习模式
│   └── patterns.jsonl            # 学习到的模式
│
├── execution/                    # 执行日志
│   └── journal.jsonl             # 执行日志
│
├── plans/                        # 归档计划文档
│
├── research/                     # 研究缓存
│
├── analytics/                    # 分析数据
│   └── spec-analytics.jsonl      # Spec 注入分析
│
├── commands/                     # 命令配置
│   └── search-system-mapping.yaml # 搜索系统映射
│
├── phases/                       # 里程碑阶段文档
│   └── {NN}-{name}/              # 阶段文档
│
├── memory/                       # 记忆存储
│
├── task-specs/                   # 任务规范
│
├── collab/                       # 人类团队协作
│   ├── specs/                    # 团队级规范
│   └── specs/{uid}/              # 个人级规范
│
├── impeccable/                   # Impeccable UI 设计上下文
│   ├── PRODUCT.md
│   ├── DESIGN.md
│   ├── design.json
│   └── design-system/            # 设计系统
│
├── .maestro/                     # Maestro 会话状态（内部）
│   └── maestro-*/status.json     # maestro 会话状态
│
├── .team/                        # Agent 团队消息总线
│   └── {session-id}/.msg/
│       └── messages.jsonl
│
├── .analysis/                    # 分析会话
├── .brainstorm/                  # 头脑风暴会话
├── .brainstorm-visualize/        # 头脑风暴可视化
├── .csv-wave/                    # CSV 波次分析
├── .debug/                       # 调试会话
├── .lite-plan/                   # 轻量计划
├── .maestro-coordinate/          # 协调会话
├── .scratchpad/                  # 临时笔记
├── .spec-index/                  # 规范索引
└── .workflow/                    # 子工作流

三、核心文件详解

state.json Schema

{
  "version": "3.0",
  "status": "idle|active",
  "current_milestone": "M1",
  "current_phase": 1,
  "milestones": [{ "id": "M1", "status": "active|completed|forked", "phases": [1, 2] }],
  "milestone_history": [{ "milestone_id": "M1", "completed_at": "ISO-8601" }],
  "artifacts": [{ "id": "ANL-001", "type": "analyze", "path": "scratch/...", "status": "completed" }],
  "artifact_archive": [{ "id": "ANL-000", "type": "analyze", "milestone": "M0", "graduated_at": "ISO-8601", "knowhow_ref": "graduated-analyze-ANL-000", "summary": "..." }],
  "accumulated_context": {
    "key_decisions": [{ "decision": "...", "rationale": "...", "source": "analyze:ANL-001", "locked_at": "ISO-8601" }],
    "deferred": [{ "title": "...", "reason": "...", "status": "open|resolved|cancelled|superseded", "source": "..." }],
    "blockers": [{ "title": "...", "severity": "...", "status": "open|investigating|resolved", "source": "..." }]
  },
  "last_pruned": "ISO-8601"
}

artifacts[] Schema

{
  "id": "ANL-001",
  "type": "analyze",
  "milestone": "M1",
  "phase": 1,
  "scope": "phase|milestone|adhoc|standalone",
  "path": "scratch/20260513-analyze-P1-auth",
  "status": "created|completed|failed",
  "depends_on": null,
  "harvested": false,
  "context_package": "scratch/20260513-analyze-P1-auth/context-package.json",
  "created_at": "ISO-8601",
  "completed_at": "ISO-8601"
}

artifact_archive[] Schema

harvest --prune 将 graduated artifacts 从 artifacts[] 迁移到此数组。文件保留在磁盘，仅 state.json 引用移动。

{
  "id": "ANL-001",
  "type": "analyze",
  "milestone": "M1",
  "path": "scratch/20260315-analyze-P2-security",
  "graduated_at": "ISO-8601",
  "knowhow_ref": "graduated-analyze-ANL-001",
  "summary": "Security audit P2 — 8 fragments → 3 wiki, 2 spec, 3 issue"
}

accumulated_context 管理

accumulated_context 随项目生命周期增长。harvest --prune 按以下规则清理：

产物生命周期

created → completed → harvested → archived
                     ↘ failed

四、知识系统

specs/ — 规范文件

使用 <spec-entry> 闭合标签格式，WikiIndexer 自动索引。

Spec 作用域：

<spec-entry category="coding" keywords="exports,naming" date="2026-05-13" source="manual">
  规范内容...
</spec-entry>

knowhow/ — 知识文档前缀

文件名格式：{PREFIX}-{YYYYMMDD}-{HHMM}.md

Learn 特殊前缀：KNW-follow-, KNW-decompose-, KNW-retro-, KNW-opinion-, KNW-investigate-, KNW-digest-

五、问题追踪

issues/issues.jsonl — 每行一个 JSON 对象：

{
  "id": "ISS-XXXXXXXX-NNN",
  "title": "问题描述",
  "severity": "blocker|critical|major|minor|cosmetic",
  "status": "open|registered|planned|in_progress|resolved|closed",
  "source": "discover|review|verify|retrospective|harvest",
  "phase": 1,
  "tags": [], "related_files": [], "task_refs": [],
  "analysis": { "root_cause": "...", "fix_direction": "...", "confidence": "high|medium|low" },
  "history": [{ "action": "created|analyzed|planned|executed|closed", "at": "ISO-8601" }]
}

• issues/issue-history.jsonl — 已关闭问题归档
• issues/discoveries/ — issue-discover 步骤会话产物

六、里程碑归档

里程碑完成时 /maestro-session-manage-manage --complete 创建归档：

1. 验证所有 run 已完成 → audit-report.md
2. scratch 产物移入 milestones/{M}/artifacts/
3. state.json.artifacts[] 移入 milestone_history[]
4. 提取 knowhow，推进下一里程碑

七、全局路径（~/.maestro/）

~/.maestro/
├── cli-tools.json              # CLI 工具配置（delegate 路由）
├── workflows/                  # 工作流定义（maestro.md, plan.md, execute.md 等 40+ 文件）
├── templates/                  # 模板系统（state.json, plan.json, task.json, workflows/ 等）
├── overlays/                   # 命令扩展（*.json, docs/, _shipped/）
└── specs/                      # 全局规范（*.md）

八、命名规则速查

Scratch 目录

格式：{YYYYMMDD}-{type}[-P{N}|-M{N}]-{slug}

Artifact 类型与命令

Session ID 格式

九、Context Package 体系

设计动机

下游命令（roadmap / analyze / plan / blueprint）消费上游产出时存在三个问题：

1. 格式耦合——每个消费者硬编码上游文件结构（如 roadmap 知道 guidance-specification.md §10 是 features）
2. 输入封闭——只支持 --from-brainstorm，无法传入任意用户文档（PRD、RFC、会议纪要）
3. 价值泄漏——brainstorm 角色分析（Decision Digest）未被 roadmap/plan 利用

Context Package 是跨命令的标准数据合约——上游按统一 schema 输出，下游按统一接口消费。

放置位置

每个产出上下文的 session 内生成 context-package.json，artifact entry 通过 context_package 字段指向它。

.workflow/scratch/20260521-brainstorm-cache/
├── guidance-specification.md         # 原始产出（保留）
├── system-architect/analysis.md      # 原始产出（保留）
├── context.md                        # 人类可读摘要（保留）
└── context-package.json              # 标准化机器合约（新增）

不放根目录——避免多 session 覆盖冲突，保留溯源。

Context Package Schema

{
  "$schema": "context-package/1.0",

  // ── 溯源 ──
  "source": {
    "type": "brainstorm|analyze|collab|import",   // 产出源类型
    "artifact_id": "BRN-001",                      // state.json artifact ID
    "session_path": "scratch/20260521-brainstorm-cache/",
    "generated_at": "2026-05-21T12:00:00Z"
  },

  // ── 需求 ── roadmap/spec-gen 主消费
  "requirements": [
    {
      "id": "F-001",
      "title": "用户认证系统",
      "description": "支持 OAuth2 + 本地密码登录",
      "priority": "must|should|may",
      "acceptance": "用户可通过 Google/GitHub OAuth 登录",
      "ref": "guidance-specification.md#§10"
    }
  ],

  // ── 约束 ── plan/execute 主消费
  "constraints": [
    {
      "id": "C-001",
      "area": "authentication",
      "constraint": "MUST use stateless JWT tokens",
      "rationale": "微服务架构下无法共享 session",
      "status": "locked|open|deferred",
      "ref": "system-architect/analysis.md#§2-Decisions"
    }
  ],

  // ── 领域知识 ──
  "domain": {
    "problem_statement": "...",
    "terminology": [
      { "term": "Tenant", "definition": "多租户隔离单元", "ref": "guidance-specification.md#§5" }
    ],
    "audience": "企业用户",
    "industry": "SaaS"
  },

  // ── 排除项 ──
  "non_goals": [
    { "title": "移动端适配", "rationale": "V2 范围", "ref": "guidance-specification.md#§6" }
  ],

  // ── 角色洞察 ── plan 直接利用（可选，仅 brainstorm 产出）
  "insights": [
    {
      "role": "system-architect",
      "area": "data-model",
      "summary": "推荐 PostgreSQL JSONB 存储租户配置",
      "ref": "system-architect/analysis.md#§3-Data-Model"
    }
  ],

  // ── 开放问题 ── analyze 重点关注
  "open_questions": [
    {
      "area": "caching",
      "question": "Redis vs Memcached for session cache?",
      "options": ["Redis（功能丰富）", "Memcached（更简单）"],
      "ref": "guidance-specification.md#§8"
    }
  ],

  // ── 原始文件引用 ── 消费者按需深读
  "references": [
    { "type": "guidance", "path": "guidance-specification.md" },
    { "type": "role-analysis", "path": "system-architect/analysis.md" },
    { "type": "role-analysis", "path": "ux-expert/analysis.md" }
  ]
}

字段说明：

Per-item ref 格式：{file}#{section-anchor}，路径相对于 session 目录。用于：

• 多源合并冲突时定位各自出处
• 消费者需要深读某条约束的完整上下文
• harvest 提取 knowledge fragment 时标注原始出处

Source Adapter 映射

统一输入：--from 标志

替代原有的 --from-brainstorm（保留为别名），支持多种输入源：

# roadmap / plan / analyze 步骤接受的 --from 参数模式（在 Session chain 内派发）：

# 按 artifact 类型+ID
roadmap --from brainstorm:BRN-001
plan --from analyze:ANL-002

# 按 session 路径
plan --from .workflow/scratch/20260521-brainstorm-cache/

# 导入外部文档（自动创建 import session）
roadmap --from @requirements.md
analyze --from @competitor-analysis.pdf

# 多源合并
plan --from brainstorm:BRN-001 --from @tech-constraints.md

# 向后兼容
roadmap --from-brainstorm SESSION-ID   # 等价于 --from brainstorm:{resolve(SESSION-ID)}

解析优先级：

多源合并策略：

外部文档导入流程

roadmap --from @prd.md
    │
    ├── 1. 创建 import session: .workflow/scratch/{date}-import-prd/
    ├── 2. 复制原始文档 → source.{ext}
    ├── 3. delegate 提取（analysis 模式）→ context-package.json
    ├── 4. 注册 artifact: { type: "import", context_package: "..." }
    └── 5. 返回 package 供消费（后续引用: --from import:IMP-001）

提取只发生一次——后续命令直接读已有 context-package.json，不重复提取。

与 accumulated_context 的关系

联动：analyze 完成时既生成 context-package（供未来 --from 查询），同时将 locked decisions 增量同步到 accumulated_context.key_decisions[]，确保全局约束传播。

各命令消费改造

反模式清单