project-os

Original source / Raw SKILL.md

---
name: project-os
description: AI project OS for autonomous loop, automated orchestration, and rule-driven execution.
version: 0.1.2
author: Peiiii
license: MIT
tags:
  - governance
  - process
  - release
  - logs
---

# Project OS

用于在新项目中快速落地“开发规范 + 迭代日志 + 发布闭环”的通用体系（Project OS），面向未来演进为可自治、可编排、自动驱动研发流程的 AI 操作系统。

## 三段式定位

1) 自治闭环  
覆盖需求—实现—验证—发布—线上冒烟—复盘的端到端闭环，系统自动推动流程完成并形成可追踪证据链。

2) 自动化编排  
将研发流程拆解为可编排的步骤与指令（commands/skills/workflows），以最小人工干预串联执行、回滚与验收。

3) 规则驱动执行  
所有行为由 Rulebook 统一约束与裁决，确保执行一致性、合规性与可审计性；如需例外必须显式声明并记录。

## 适用场景

- 想把一套严格交付流程迁移到其他项目。
- 需要在团队内统一验证/冒烟/发布规范。

## 启用方式（必须先初始化才生效）

本 Skill 安装后不会自动生效，首次使用时需要初始化；初始化完成后规则与流程才会被执行。

## 初始化流程（首次使用）

1) 用户安装本 Skill 并开始与 agent 对话。  
2) agent 检测到目标项目尚未初始化（如缺少 `AGENTS.md`/`commands`/`docs/logs`）。  
3) agent 主动提示初始化必要性与影响，并请求确认。  
4) 用户确认后，agent 自动完成初始化并反馈结果。  

## 初始化会做什么

- 生成/更新 `AGENTS.md`（若已存在，则合并而非覆盖）
- 生成/更新 `commands/commands.md`
- 生成/更新 `docs/logs` 与 `docs/workflows`
- 保证规则、指令索引、日志制度完整落地

## 手动初始化（仅作为兜底）

将本 Skill 的模板复制到目标项目根目录（若已有文件，需合并而非覆盖）：

```bash
cp -R <skill>/assets/commands ./commands
cp -R <skill>/assets/docs ./docs
cp <skill>/assets/AGENTS.template.md ./AGENTS.md
```

## 关键约束

- “完成所有/完成全部”默认执行完整上线闭环（migrations -> deploy -> 线上冒烟）。
- 冒烟测试默认使用非仓库目录环境，禁止写入仓库子目录。
- 每次开发阶段结束必须完成 build/lint/tsc + 冒烟（如适用）。

## 扩展与维护

- 新增/修改指令：更新 `commands/commands.md` 并同步 AGENTS 索引。
- 新增/修改规则：只在 AGENTS 的 Rulebook 维护。
- 发布流程统一写入 `docs/workflows/npm-release-process.md`。

## 模板索引

- `assets/AGENTS.template.md`
- `assets/commands/commands.md`
- `assets/docs/logs/TEMPLATE.md`
- `assets/docs/logs/README.md`
- `assets/docs/workflows/npm-release-process.md`


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### assets/AGENTS.template.md

```markdown
1. 假设你是ceo+cto(架构师)+产品经理的综合体，从这个角度来思考所有问题
2. 不要管开发代价，永远只考虑最终最佳方案，反正都是你来开发
3. 每次完成一个阶段都要至少做代码验证，包括不限于build, lint, tscheck；如涉及可运行功能/用户可见改动，必须追加至少一条冒烟测试（真实命令/请求），默认使用非 local/非仓库目录的环境，禁止将烟测安装/数据写入仓库子目录。
4. 涉及后端或数据库变更的发布必须执行远程 migration，并对关键 API 做线上冒烟验证后才算阶段完成
5. 任何“发布/上线”必须形成闭环：migrations apply -> deploy -> 线上冒烟验证；缺一不可，否则视为未完成
6. 发布部署必须覆盖所有需要发布的组件（registry/console/cli 等），若用户未明确范围必须先确认；缺项视为流程缺陷
7. 若用户明确要求“直接发布/不做选择”，默认执行全量发布闭环（覆盖所有本次变更涉及的组件），不得再次要求用户决策
8. NPM 包发布流程详见 `docs/workflows/npm-release-process.md`，必须遵循
9. 用户指令中出现“完成所有”“完成全部”等表述时，默认执行完整上线闭环：远程 migration -> 全量组件发布/部署（registry/console/cli/npm 包等，含版本号提升与发布）-> 线上冒烟验证；无需再次确认范围，不得省略任一环节。

---
负面清单
- 同一个功能，逻辑不应该多次实现。唯一性。
- UI 组件禁止依赖业务逻辑

---
不急，接下来我们采取一种面向未来的逆天超级快节奏的开发方式。


## 迭代制度（docs/logs）

- 每个迭代在 `docs/logs` 下新增一个目录
- 目录内按版本号建立子目录，命名为 `v0.0.1-版本的slug`（语义化）
- 每个版本目录至少包含：
  - 迭代完成说明（改了什么）
  - 测试/验证/验收方式
  - 发布/部署方式
- 可选文档：PRD、讨论记录等

## 指令/Command 机制

- 新增指令统一记录在 `commands/commands.md`，并在此处索引
- 约定元指令：输入 `/new-command` 触发创建新指令流程
- 指令文件结构：每条指令包含名称、用途、输入格式、输出/期望行为
- 后续新增或修改指令时，更新 `commands/commands.md` 并保持此处索引最新
- 已有指令：
  - `/new-command`：创建新指令
  - `/config-meta`：调整或更新本文件（AGENTS.md）的机制/元信息
  - `/commit`：进行提交操作（提交信息需使用英文）
  - `/validate`：运行项目验证，至少包含 `build`、`lint`、`tsc`，必要时冒烟测试

## 规则/Rule 机制

- 规则直接维护在本文件末尾的 **Rulebook** 区域
- 约定元指令：输入 `/new-rule` 触发创建新规则流程
- 规则条目包含：名称（英文 kebab-case）、约束/适用范围、示例/反例、执行方式（工具/流程）、维护责任人
- 后续新增或修改规则时，直接在本文件的 **Rulebook** 区域追加/更新
- 默认所有规则必须严格遵守（无额外声明即视为强制）；如需例外必须在规则中明确说明

## Rulebook

- **post-dev-stage-validation**：每个开发阶段结束必须做验证，至少运行 `build`、`lint`、`tsc`（如确认为无关可有理由地省略），如条件允许应做基础冒烟测试。
- **no-self-commit-without-request**：除非用户明确要求，否则禁止擅自提交/推送代码。
- **use-chinese-when-communicating**：与用户交流时使用中文。
- **smoke-test-required**：所有用户可见/可运行行为改动必须附带冒烟测试，使用真实命令或接口调用验证主路径成功；发布/上线前必须记录冒烟结果（命令与观察点）。执行方式：按组件选择对应 CLI/API/UI 最小可行流程；责任人：当次交付 owner。
- **smoke-no-local-repo-writes**：冒烟测试默认在非 local/非仓库目录环境执行；禁止将冒烟测试的安装/数据写入仓库目录或其子目录，需使用全局/隔离路径并在测试后清理。执行方式：优先 global scope 或临时目录；责任人：当次交付 owner。
- **reply-prefix-required**：所有对用户的回复必须以前缀`[我严格遵守规则]`开头（含本条指令当次起立即生效）；执行方式：所有输出前置该前缀；责任人：当前助手。

```

### assets/commands/commands.md

```markdown
# Commands

- `/new-command`: 新建一条指令的元指令。流程：确认名称、用途、输入格式、输出/期望行为，写入本文件并保持 `AGENTS.md` 索引同步。
- `/config-meta`: 调整或更新 `AGENTS.md` 中的机制/元信息（如规则、流程、索引等）的指令。执行时需明确变更点与预期影响。
- `/commit`: 进行提交操作（提交信息需使用英文）。
- `/validate`: 对项目进行验证，至少运行 `build`、`lint`、`tsc`，必要时补充冒烟测试。执行前需确认验证范围和可跳过项。

（后续指令在此追加，保持格式一致。） 

```

### assets/docs/logs/TEMPLATE.md

```markdown
# YYYY-MM-DD <Title>

## 背景 / 问题

- 为什么要做（用户痛点/动机/现状问题）

## 规则（可选）

- 规划类文档不要写具体工期，只写里程碑顺序与验收标准
- 规划类文档文件名建议以 `.plan.md` 结尾，便于区分“规划”与“实现日志”

## 决策

- 做什么、不做什么（关键取舍）

## 变更内容

- 用户可见变化（CLI 行为/输出/默认值等）
- 关键实现点（指向 core/cli 的关键模块即可）

## 验证（怎么确认符合预期）

保持轻量：3～6 条命令 + 明确的“验收点”。

```bash
# build / lint / typecheck
pnpm build
pnpm lint
pnpm typecheck

# smoke-check（按需补充）
pnpm -s cli --help
```

验收点：

- 写清楚“看到什么输出/行为才算对”

## 发布 / 部署

如果这次变更会影响 npm 包或线上环境，需要写清楚如何发布。

```bash
# 1) 写 changeset（选择受影响的 packages）
pnpm changeset

# 2) 本地验证
pnpm release:check
pnpm release:dry

# 3) 版本号 & changelog
pnpm release:version

# 4) 发布到 npm（需要 NPM_TOKEN 或已登录）
pnpm release
```

备注：

- 需要更详细的发布说明时，引用 `docs/workflows/npm-release-process.md`，不要在每篇日志里重复一遍。

## 影响范围 / 风险

- Breaking change?（是/否）
- 回滚方式（如果需要）

```

### assets/docs/logs/README.md

```markdown
# Logs

- `docs/logs/v0.0.1-mvp/README.md`
- `docs/logs/v0.1.0-headless/README.md`

## 写日志的标准

每次改动完成后新增一篇日志文件，至少包含：

- 做了什么（用户可见 + 关键实现点）
- 怎么验证（轻量 smoke-check + `build/lint/typecheck`）
- 怎么发布/部署（如果会影响 npm 包/线上环境；详细流程引用 `docs/workflows/npm-release-process.md`）

模板：`docs/logs/TEMPLATE.md`

## 规划规则

- 规划文档禁止写具体花费时间/工期（例如“3 天”“1 周”）；只写里程碑顺序、交付物与验收标准。
- 规划类文档建议以 `.plan.md` 结尾（例如 `YYYY-MM-DD-xxx.plan.md`），便于区分“规划”与“实现/复盘”

```

### assets/docs/workflows/npm-release-process.md

```markdown
# NPM Package Release Process

Scope: publish npm packages in `packages/*`.
This does NOT cover registry/console deployment.

## Prereqs
- npm auth available via one of:
  - `.npmrc.publish.local` (preferred, ignored by git)
  - `NPM_TOKEN` env var
  - `npm login` (interactive)

## Standard flow
1) Create changeset
```bash
pnpm changeset
```

2) Bump versions + changelogs
```bash
pnpm release:version
```

3) Publish
```bash
pnpm release:publish
```

Notes:
- `release:publish` should run `release:check` (build + lint + typecheck) before publishing.
- `release:publish` should create git tags automatically.

```