copilot-team-scaffold

Initialize a multi-agent AI development framework for any project. Creates .github/ structure with agents, hooks, instructions, prompts, and planning-with-fi...

Security Scan

The skill largely implements what it claims (scaffolding hooks, agent files, and a planning skill) but it assumes and runs many local tools and accesses local session files without declaring those requirements — review the scripts and run in a sandbox/branch before trusting it.

Purpose & Capability

The files and templates match the stated goal of scaffolding a multi-agent development framework (.github hooks, .github/skills, AGENTS.md, planning-with-files). However the skill's manifest lists no required binaries or env vars while the included hooks/scripts clearly call node, python/python3, git, ruff, pyright, npx/tsc, pytest, vitest, etc. The absence of declared runtime dependencies is an inconsistency (not necessarily malicious) that the user should be aware of.

Instruction Scope

SKILL.md instructs copying templates into the repo and generating many persistent files — that's expected — but the provided hook scripts do more: they execute linters/tests, run git commands, write structured session logs under .github/session-logs and .github/lessons-learned.md, and the Python catchup script reads from a per-user directory in the home (~/.claude/projects). Those behaviors access broad filesystem state (including per-user session data) and can execute repository code as part of tests — scope is wider than a simple file scaffold and could surface sensitive data or execute arbitrary project code.

Install Mechanism

No external install/downloads are performed by the skill (instruction-only plus templates included in the package). No remote URLs or extracted archives were observed, which lowers supply-chain risk. The scripts are local and will be copied into the repository rather than pulled from an arbitrary server.

Credentials

The skill declares no required env vars or credentials but the scripts reference environment variables (PLANNING_WITH_FILES_ROOT/PLAN_DIR) and depend on many developer tools (node, python, git, ruff, pyright, tsc, pytest, vitest, npx). Those tool and path assumptions are not declared in the metadata. Additionally, the Python catchup script reads/writes under the user's home (~/.claude/...), so it implicitly depends on and accesses per-user session storage — this is a disproportionate implicit environment access that should be documented and inspected.

Persistence & Privilege

The scaffold will write persistent files into the repository (.github/hooks, .github/skills, docs/, AGENTS.md, .github/session-logs, lessons files). Hooks are executable code that run during agent lifecycle events and thus gain the ability to run commands on your environment (linters, tests, git). The skill does not request 'always: true' and does not change other skills' configs, but because the hooks/scripts will persist in repo and run automatically as part of lifecycle events, you should review them before committing to a main branch.

What to consider before installing

This skill appears to implement the scaffold it describes, but it makes implicit assumptions and will add executable hook scripts to your repo. Before installing or committing: 1) Review the hook scripts (templates/hooks/scripts/*.js, session-catchup.py) for any commands you don't expect. 2) Be aware they call tools that must be present (node, python, git, ruff, pyright, tsc/npx, pytest/vitest); install or adjust them if you proceed. 3) The Python script reads from ~/.claude/projects — if you store sensitive session data there, inspect or remove that behavior. 4) Test the scaffold in an isolated branch or disposable repository first (or run with hooks disabled) to avoid accidental execution of tests or lints against your main workspace. 5) If you don't want automatic blocking behavior, edit subagent-stop.js to adjust or disable the blocking/lesson-writing logic. If you want me to, I can list the exact files/lines that reference home-directory session data and external tools, or produce a diff that removes or neutralizes the implicit behaviors.

为新项目搭建完整的 AI 辅助开发框架。把 Copilot 从代码补全工具变成一个有组织、有纪律的虚拟开发团队。

核心理念

需求文档 → 设计规格 → 任务分解 → Agent 分发执行 → 自动化保障（hooks + instructions）

通过以下四层保障 AI 执行质量：

• 文件化的约束（AGENTS.md）— 明确每个角色的职责和规范
• 自动化的保障（hooks）— 覆盖 6 个生命周期事件：上下文注入、质量门禁、降级策略
• 持久化的记忆（memories + sessions + lessons）— 弥补 AI 的上下文遗忘，自动积累教训
• 结构化的任务（spec-flow + tasks.md）— 确保需求到代码的可追溯性

运行时生命周期

SessionStart ──→ PreToolUse ──→ PostToolUse ──→ SubagentStart ──→ SubagentStop ──→ Stop
     │                │               │               │                │            │
  计划恢复         计划上下文       更新提醒       审计记录       质量验证门禁     完成度检查
  教训注入                                                        降级策略        会话摘要
  趋势分析

学习闭环

失败 → 自动记录(lessons-learned.md) → 统计分析(趋势) → 注入新会话 → 预防重犯

前提条件

此 skill 假设以下全局 skill 已安装：

• spec-flow — 需求拆解工作流（proposal → requirements → design → tasks）
• planning-with-files — 会话级文件计划（可选，将作为项目级 skill 生成）

⚠️ 交互规则

使用分阶段确认工作流。每个阶段完成后等待用户确认再继续。

---

Phase 1: 采集项目信息

向用户提出以下问题（使用 vscode_askQuestions 或对话形式）：

必填信息

1. 项目名称：用于 spec-flow 目录名和 AGENTS.md 标题（如 CMC-ARD系统）
2. 项目简述：一句话描述项目做什么
3. 后端技术栈（选择一项）：
   • Python / FastAPI + Tortoise ORM
   • Python / FastAPI + SQLAlchemy
   • Python / Django
   • Node.js / Express
   • Go / Gin
   • Java / Spring Boot
   • 无后端
4. 前端技术栈（选择一项）：
   • React + TypeScript + Ant Design
   • React + TypeScript + MUI
   • Vue 3 + TypeScript
   • Next.js
   • 无前端
5. 数据库（选择一项）：
   • Azure SQL Server
   • PostgreSQL
   • MySQL
   • SQLite
   • MongoDB
   • 无数据库
6. 需要哪些 Agent 角色（多选，建议全选相关的）：
   • 后端开发Agent
   • 前端开发Agent
   • AI工程师Agent
   • 测试工程师Agent
   • 需求分析工程师Agent
   • 架构师Agent（只读不写代码）

可选信息

7. 认证方式：SSO JWT / 自建用户系统 / 无认证
8. CI/CD：Docker Compose / GitHub Actions / Azure DevOps / 无
9. 表前缀：数据库表名前缀（如 custom_ardqc_）
10. 代码检查工具：ruff（Python）/ eslint（TS）/ 其他

Phase 1 完成后

输出采集到的配置摘要，等待用户确认：

📋 **项目信息采集完成**

- 项目名：{{PROJECT_NAME}}
- 后端：{{BACKEND_STACK}}
- 前端：{{FRONTEND_STACK}}
- 数据库：{{DATABASE}}
- Agent 角色：{{AGENT_LIST}}

✅ 确认无误后说 "继续" 开始生成文件
✏️ 有修改请直接说

---

Phase 2: 生成静态文件

以下文件直接从 templates/ 目录复制，无需定制：

2.1 Hooks（自动化钩子）

从 templates/hooks/ 复制到项目的 .github/hooks/：

.github/hooks/
├── planning-with-files.json          # 全生命周期 hook 配置（6 个事件）
├── post-tool-lint.json               # 自动 lint hook 配置
├── post-tool-lint.js                 # lint 执行脚本
└── scripts/
    ├── planning-paths.js             # 路径解析共享模块
    ├── session-log.js                # 审计日志共享模块（NEW）
    ├── session-start.js              # SessionStart: 恢复上下文 + 教训注入 + 趋势分析
    ├── pre-tool-use.js               # PreToolUse: 注入计划摘要
    ├── post-tool-use.js              # PostToolUse: 提醒更新计划
    ├── subagent-start.js             # SubagentStart: 审计记录（NEW）
    ├── subagent-stop.js              # SubagentStop: 质量验证门禁 + 降级策略（NEW）
    └── agent-stop.js                 # Stop: 完成度检查 + 会话摘要

planning-with-files.json 覆盖 6 个生命周期事件：

• SessionStart(15s) — 计划恢复 + 教训注入 + 趋势分析 + 日志清理
• PreToolUse(15s) — 注入当前计划上下文
• PostToolUse(15s) — 提醒更新计划文件
• SubagentStart(10s) — 审计记录 Agent 启动
• SubagentStop(120s) — 核心门禁：ruff + pyright + tsc + 关联测试 + 降级策略
• Stop(10s) — 任务完成度检查 + 会话摘要

SubagentStop 验证门禁 详解：

1. git diff 获取变更文件列表
2. Python 文件 → ruff check + pyright
3. TypeScript 文件 → tsc --noEmit
4. 自动映射关联测试文件并运行（pytest / vitest）
5. 验证失败 → block 让 agent 继续修复
6. 连续失败 3 次 → 降级到人工，不再 block（防止死循环）
7. 每次失败自动追加到 lessons-learned.md

session-log.js 共享模块：

• appendLog(sessionId, event, details) — 结构化日志追加
• cleanupLogs() — 自动清理过期日志（>30天 / >100个）+ 过期重试计数器（>1天）
• 日志文件格式：.github/session-logs/YYYY-MM-DD_<sid8>.md

2.2 planning-with-files Skill（项目级）

从 templates/skills/planning-with-files/ 复制到 .github/skills/planning-with-files/：

.github/skills/planning-with-files/
├── SKILL.md                          # Skill 定义
├── templates/
│   ├── task_plan.md
│   ├── findings.md
│   └── progress.md
└── scripts/
    └── session-catchup.py

2.3 Sessions 工作区

从 templates/docs/ 复制：

docs/sessions/README.md               # 会话目录说明

---

Phase 3: 生成动态文件

以下文件需要根据 Phase 1 采集的信息动态生成。

3.1 根 AGENTS.md

创建 AGENTS.md，结构如下（用采集到的信息填充）：

# {{PROJECT_NAME}} — Project Guidelines

> 根目录 AGENTS.md — 全局规则，适用于所有模块。
> 子模块细节见各目录下的 `AGENTS.md`。

## 项目概述
{{PROJECT_DESCRIPTION}}

## 架构
{{根据技术栈生成架构图}}

## 安全合规
- 禁止硬编码敏感信息
- 日志脱敏
- 输入验证
- .env 不入库

## 配置管理
{{根据技术栈生成配置说明}}

## 代码质量
- 类型安全
- 异步编程
- 错误处理
- 结构化日志
- 代码简洁性

## 数据库
{{如有数据库，生成表前缀和数据隔离规则}}

## 测试策略
| 模式 | 适用场景 |
|------|----------|
| TDD | 纯逻辑、边界条件多 |
| 边写边测 | REST 端点 |
| 实现后补 | AI 输出/UI 交互 |

## Agent 分配规则
{{根据选择的 Agent 角色生成分配表}}

## Agent 执行约定
1. 执行前：读取目标模块的 AGENTS.md
2. 执行中：遵守安全合规与代码质量要求
3. 联合开发：读取相关模块 AGENTS.md，确保接口兼容
4. 自动分发：根据任务类型通过 runSubagent 分发给对应 Agent
5. 跨模块感知：识别所有受影响模块，分别调度对应 Agent

## 模块 AGENTS.md 规则
- 每个模块开发前须先创建该模块的 AGENTS.md
- 必须包含：模块功能、技术栈、接口定义、数据模型、注意事项
- 功能变更后同步更新

## 构建与运行
{{根据技术栈生成命令}}

3.2 Agent 定义文件

为每个选择的 Agent 在 .github/agents/ 下创建 .agent.md。

Agent 文件基本结构（以后端开发Agent为例）：

---
description: "后端开发Agent。Use when implementing backend API endpoints, routes, ORM models, schemas, business services, or any backend code. Triggers: 后端开发, backend, API开发, 服务端, {{BACKEND_FRAMEWORK}}, ORM, schema, service, 数据库"
name: "后端开发Agent"
tools: [read, edit, search, execute, agent, todo]
---

你是 {{PROJECT_NAME}} 的**后端开发专家**。

## 角色定位
你负责所有后端代码的开发，包括 API 端点、ORM 模型、Schema、业务服务层、后台任务。

## 技术栈
{{根据后端技术栈填充}}

## 执行前准备
1. 阅读 `.spec-flow/active/{{PROJECT_SLUG}}/design.md` 中的相关章节
2. 阅读目标模块的 `AGENTS.md` 文件
3. 检查依赖任务是否已完成
4. 创建新模块时，必须先创建该模块的 `AGENTS.md`

## 约束
- 遵守根目录 AGENTS.md 的安全合规和代码质量要求
- 所有 API 必须 async/await
- 使用结构化日志
- 类型安全

各角色要点：

Agent	文件名	关键特征
后端开发Agent	backend-developer.agent.md	负责 API/ORM/Service/Task
前端开发Agent	frontend-developer.agent.md	负责组件/Hooks/状态管理/i18n
AI工程师Agent	ai-engineer.agent.md	负责 LLM/文档解析/规则引擎
测试工程师Agent	test-engineer.agent.md	负责 pytest/vitest/覆盖率
需求分析工程师Agent	requirements-analyst.agent.md	负责文档/手册/需求追踪
架构师Agent	architect.agent.md	只读不写代码，负责设计评审

3.3 Instructions（指令约束）

在 .github/instructions/ 下生成：

3.3.1 通用 Instructions（直接复制）

• planning-with-files.instructions.md — 从 templates/instructions/ 复制
• testing.instructions.md — 从 templates/instructions/ 复制
• spec-flow-run-task.instructions.md — 从 templates/instructions/ 复制（需替换 {{PROJECT_SLUG}}）

3.3.2 技术栈 Instructions（动态生成）

如果有后端，生成 backend-*.instructions.md，包含：

• 该后端框架的异步模式约束
• ORM 使用规范
• 日志框架约束
• lint 工具和配置

如果有前端，生成 frontend-*.instructions.md，包含：

• 组件规范
• i18n 规则
• 状态管理约束
• UI 框架使用规范

3.4 run-task.prompt.md

在 .github/prompts/ 下生成：

---
description: "Execute a task from tasks.md by task ID (e.g. T-008)."
agent: "agent"
argument-hint: "Task ID, e.g. T-008"
---
Execute the following task from the project task list.

## Steps

1. Read the task list: [tasks.md](.spec-flow/active/{{PROJECT_SLUG}}/tasks.md)
2. Find the task matching `{{ input }}` — extract its description, dependencies, status, complexity, and assigned Agent
3. **Dependency check**: If any dependency task is not ✅ Done, stop and report which are blocking
4. **Read module AGENTS.md**: Read the `AGENTS.md` file(s) for the target module(s)
5. **Execute**: Implement the task following the constraints in [AGENTS.md](AGENTS.md)
6. **Test**: If the task's test mode is TDD or 边写边测, write/update tests
7. **Verify**: Run the relevant test suite and confirm passing
8. **Report**: Summarize what was done, files changed, and any follow-up needed

---

Phase 4: 初始化 Spec-Flow 落地目录

创建 spec-flow 的项目落地目录：

.spec-flow/active/{{PROJECT_SLUG}}/

不要在这里创建 proposal.md / requirements.md 等文件 — 那些由 spec-flow skill 在实际执行时生成。只创建空目录。

---

Phase 5: 初始化数据层与记忆模板

5.1 教训知识库

从 templates/lessons-learned.md 复制到 .github/lessons-learned.md。此文件由 SubagentStop hook 自动写入验证失败记录，SessionStart hook 自动读取注入。

5.2 审计日志目录

创建 .github/session-logs/ 目录（空），并在项目 .gitignore 中添加：

# Copilot session logs (auto-generated, not tracked)
.github/session-logs/

5.3 记忆模板

提示用户手动或通过 memory tool 创建以下仓库级记忆文件：

/memories/repo/code-style.md      — 代码风格备忘（空模板，使用中积累）
/memories/repo/execution-discipline.md — 执行纪律备忘（空模板，犯错后记录）

内容建议：

code-style.md:

# 代码风格备忘

<!-- 使用过程中积累的代码风格约定 -->

execution-discipline.md:

# 执行纪律备忘

## 任务执行 Checklist（每个任务必须）

1. 完整读取 tasks.md §0 — 开发约束、Agent规则、执行约定
2. 必须通过 runSubagent 派发给指定 Agent 执行
3. 模块开发前先创建该模块的 AGENTS.md
4. 执行前准备 — 读 AGENTS.md → 了解模块结构 → 检查依赖完成
5. 安全合规 — 禁止硬编码密码、日志脱敏、输入验证
6. 代码质量 — 类型提示、async/await、错误处理、结构化日志
7. 测试策略 — 按任务指定的测试模式执行

## 教训

<!-- 犯错后在此记录，避免重复 -->

5.4 全局用户记忆（首次使用框架时初始化）

通过 memory tool 检查并创建以下全局记忆文件。这些文件跨项目持久化，每次会话自动加载到上下文中。如果已存在则跳过（memory create 对已有文件会失败，这是预期行为）。

/memories/agent-principles.md — Agent 行为原则

# Agent 行为原则（跨项目通用）

## 独立技术判断
- 用户提问 ≠ 要求修改；先独立分析对错，再给结论
- 推理基于技术事实，不基于"用户暗示了方向"

## 先讨论后动手
- 收到功能修改/新增请求时，**不要直接改代码**，先给出修改方案与用户讨论
- 用户明确确认方案后才可开始写代码

## 约束优先
- 执行任务前先读项目约束文件（AGENTS.md、instructions/），不因任务简单就跳过
- 安全合规不可跳过：禁止硬编码敏感信息、日志脱敏、输入验证

## 待办状态即时更新（严格执行）
- 每完成一个 todo，**立即调用 manage_todo_list 标记 completed**，再做下一个
- 禁止批量完成后一次性更新——上下文压缩会吞掉未持久化的状态
- 节奏：mark in-progress → 执行 → mark completed → 下一个 mark in-progress

## 分析→分发→执行
- 多模块任务先全面分析，再按职责分派给对应 Agent（runSubagent），不由主 Agent 直接写任务代码
- 模块开发前先读取/创建该模块的 AGENTS.md；功能变更后同步更新

/memories/copilot-hooks.md — Hooks 配置笔记

# Copilot Chat Hooks 配置笔记

- 文档：https://code.visualstudio.com/docs/copilot/customization/hooks
- 配置位置：`.github/hooks/*.json`（项目级）、`~/.copilot/hooks/`（全局级）
- 事件名必须 PascalCase：SessionStart, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop
- 需同时设 `command`（默认）+ `windows`（Windows 覆盖）；`bash` 仅映射 osx/linux

## Windows 环境
- bash.exe 在 RemoteApp 下会弹控制台窗口 → 已全部迁移到 Node.js 脚本
- hook 脚本用 `.js` + `node` 执行，子进程加 `windowsHide: true`

执行逻辑：对每个文件先用 memory view 检查是否存在，不存在才用 memory create 创建。已有文件保持不动，不覆盖用户积累的个性化内容。

---

Phase 6: 输出检查清单

全部文件生成后，输出最终清单：

✅ **AI 开发框架初始化完成**

### 已创建文件

**Hooks（自动化保障 — 6 个生命周期事件）:**
- .github/hooks/planning-with-files.json（6 事件配置）
- .github/hooks/post-tool-lint.json + post-tool-lint.js
- .github/hooks/scripts/ (8 个脚本：planning-paths, session-log, session-start, pre-tool-use, post-tool-use, subagent-start, subagent-stop, agent-stop)

**Skills（技能包）:**
- .github/skills/planning-with-files/ (SKILL.md + templates + scripts)

**Agents（专职角色）:**
- .github/agents/ ({{N}} 个 Agent 定义文件)

**Instructions（约束注入）:**
- .github/instructions/ ({{N}} 个指令文件)

**Prompts（快捷入口）:**
- .github/prompts/run-task.prompt.md

**数据层（学习闭环）:**
- .github/lessons-learned.md（教训知识库，SubagentStop 自动写入）
- .github/session-logs/（审计日志目录，已加入 .gitignore）

**记忆文件（3 层记忆体系）:**
- /memories/agent-principles.md（全局 — Agent 行为原则，首次创建）
- /memories/copilot-hooks.md（全局 — Hooks 配置笔记，首次创建）
- /memories/repo/code-style.md（仓库级 — 代码风格备忘）
- /memories/repo/execution-discipline.md（仓库级 — 执行纪律备忘）

**项目文档:**
- AGENTS.md（根级约束）
- docs/sessions/README.md

**Spec-Flow 落地目录:**
- .spec-flow/active/{{PROJECT_SLUG}}/

### 运行时保障一览

| 事件 | 脚本 | 功能 |
|------|------|------|
| SessionStart | session-start.js | 计划恢复 + 趋势分析 + 教训注入 + 日志清理 |
| PreToolUse | pre-tool-use.js | 注入当前计划上下文 |
| PostToolUse | post-tool-use.js | 提醒更新计划文件 |
| SubagentStart | subagent-start.js | 审计记录 Agent 启动 |
| SubagentStop | subagent-stop.js | 质量门禁 + 降级策略 + 教训记录 |
| Stop | agent-stop.js | 完成度检查 + 会话摘要 |

### 下一步

1. 🔧 根据项目实际需求完善 `AGENTS.md` 中的架构图和配置说明
2. 📝 说 **"spec-flow"** 或 **"spec mode"** 开始拆解需求
3. 🚀 需求拆解完成后，说 **/run-task T-001** 开始执行第一个任务
4. 📊 SubagentStop 会自动验证代码质量，lessons-learned.md 自动积累经验

---

静态文件内容参考

以下文件内容存放在 templates/ 目录中，scaffold 执行时直接复制到目标项目。详见各模板文件。

post-tool-lint.js 适配说明

模板中的 lint 脚本支持 Python（ruff）和 TypeScript（eslint）。如果项目使用其他语言/lint 工具，在 Phase 2 复制后需要修改 post-tool-lint.js 中的扩展名判断和工具调用。

planning-paths.js 配置

默认 PLANNING_ROOT = 'docs/sessions'。如果项目需要不同的会话目录，可通过环境变量 PLANNING_WITH_FILES_ROOT 覆盖。

spec-flow-run-task.instructions.md 路径

模板中使用 {{PROJECT_SLUG}} 占位符，需替换为实际的 spec-flow 目录名。例如 .spec-flow/active/CMC-ARD系统/tasks.md。