# aidlc-skill

**Repository Path**: asahi_software/aidlc-skill

## Basic Information

- **Project Name**: aidlc-skill
- **Description**: 把亚马逊 [awslabs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows) 
打包成：
一个自包含目录 +一个技能
.agents/ 里是完整的引擎（方法论、33 个阶段、11 个 scope、14 个 agent、sensors、hooks、工具），
aidlc-workflows 是唯一需要加载的技能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aidlc-workflows 技能（AI-DLC 2.9.0 单技能发行版）

把亚马逊 [awslabs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows) 2.9.0 打包成一个自包含目录加一个技能。`.agents/` 里是完整引擎，包含方法论、33 个阶段、11 个 scope、14 个 agent、传感器与工具；`aidlc-workflows` 是唯一需要加载的技能。

使用只有三步。把本仓库的 `.agents/` 整个复制到项目根目录，让 coding agent 加载 `.agents/skills/aidlc-workflows/SKILL.md`，然后用一句话描述要做的事，例如「给订单服务加一个取消接口」，scope 由引擎识别。不需要安装上游，不需要跑 `aidlc config`，也不需要别的技能。工作空间 `aidlc/` 会在第一次创建 intent 时自举，内容取自 `.agents/tools/data/memory-seed/`。

## 30 秒上手

```bash
cd your-project
bun .agents/tools/aidlc.ts --version   # aidlc 2.9.0 (runtime 2.9.0)
bun .agents/tools/aidlc.ts --status    # No active AI-DLC workflow found.
```

两条命令都返回 0 就装好了。这时项目里还没有 `aidlc/` 目录，这是正常的，工作空间要等第一次创建 intent 才生成。

## 前置条件：Bun

`bun --version` 必须有输出，本仓库在 Bun 1.4.2 加 Windows 11 上验证过。引擎在模块作用域依赖 `bun:ffi` 和 `Bun.*` 全局量，Node 跑不起来。

```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```

Windows 上有个常见的坑：如果 `where bun` 命中的是 `C:\Program Files\nodejs\bun` 或 `bun.cmd`，那是 npm 残留的死链，会遮蔽真正的 `%USERPROFILE%\.bun\bin\bun.exe`，命令会报 `系统找不到指定的路径`。用 `npm ls -g --depth=0` 确认列表里没有 `bun`，然后把那些 shim 删掉。完整排查步骤见 [usage-guide.md](usage-guide.md) 第 1 节。

## 只有一个技能

stage runner（`aidlc-<stage>`）、scope runner（`aidlc-<scope>`）与会话类技能（`aidlc-session-cost`、`aidlc-replay`、`aidlc-outcomes-pack`、`aidlc-knowledge`）都没有安装。要按阶段或按范围运行，用引擎的 flag：

```bash
bun .agents/tools/aidlc.ts engine orchestrate next --stage <slug> --single   # 只跑一个阶段，不动主指针
bun .agents/tools/aidlc.ts --scope <name>                                    # 指定 scope 运行
```

注意 `--stage` 这类 flag 不是顶层 CLI 参数，实测顶层会报 `error: unknown command '--stage'`，它由引擎的 `orchestrate` 面消化。权威清单是 `bun .agents/tools/aidlc.ts engine orchestrate help`。

## 安装后你会看到什么

```text
your-project/
  .agents/                                   ← 引擎，复制进来，不要手改
    skills/aidlc-workflows/SKILL.md          ← 唯一需要加载的技能
    tools/aidlc.ts                           ← CLI 入口
    agents/ scopes/ sensors/ hooks/ ...      ← persona、scope、传感器、hook 模块
  aidlc/                                     ← 首次创建 intent 后才出现的工作空间
    spaces/default/intents/<YYMMDD>-<label>/
```

`.agents/` 的内部结构不要改动。引擎按目录名 `.agents` 推导全部内部路径，改名或者换层级会直接失效。

## 发行物基线

| 项 | 值 | 来源 |
| --- | --- | --- |
| 上游版本 | 2.9.0（`## [2.9.0] - 2026-09-15`） | 上游 `CHANGELOG.md:4` |
| 许可 | MIT-0 | 上游 `package.json` 的 license 字段，以及 `LICENSE` |
| 阶段数 | 33，initialization 3、ideation 7、inception 9、construction 7、operation 7 | `.agents/tools/data/stage-graph.json` |
| scope 数 | 11，EXECUTE 阶段数从 8 到 33 | `.agents/tools/data/scope-grid.json` |
| agent 数 | 14 | `.agents/agents/` |
| sensor 数 | 6 | `.agents/sensors/` |
| hook 模块 | 18 个 `.ts` | `.agents/hooks/` |
| 协议文件 | 9 | `.agents/aidlc-common/protocols/` |
| 发行物体量 | 249 个文件，约 7.5 MB | 实测 |

## `.agents/` 是生成产物

不要手改 `.agents/` 下的任何文件，下次同步会整目录覆盖。要改内容或者换上游版本，先改 overlay 输入，也就是 `scripts/harness/agents/manifest.ts` 与 `scripts/harness/agents/skills/aidlc-workflows/**`，或者改 `scripts/sync-aidlc.ts` 里的补丁表，然后运行：

```bash
bun scripts/sync-aidlc.ts   # 重新打补丁、跑上游打包器、重写身份、镜像投影、跑全部校验
```

上游映射、补丁表、校验清单，以及没有 hook 系统时哪些守卫不会触发，都写在 [migration-guide.md](migration-guide.md)。

## 文档导航

| 文件 | 读者 | 内容 |
| --- | --- | --- |
| [usage-guide.md](usage-guide.md) | 使用方 | 逐步上手：复制什么、每步怎么验证、出问题怎么查 |
| [docs/ai-dlc-2.9.0-skill-overview.md](docs/ai-dlc-2.9.0-skill-overview.md) | 使用方、评估者 | 单篇总览：接入步骤、流程档位与门数、机制速览、已知边界 |
| [migration-guide.md](migration-guide.md) | 维护者 | 上游映射、补丁表、守卫边界 |
| [docs/README.md](docs/README.md) | 评估者 | 五份文档的索引、事实基线、术语表、素材层说明 |
| [docs/01](docs/01-ai-dlc-methodology.md)、[docs/02](docs/02-technical-practice.md)、[docs/03](docs/03-collaboration-models.md)、[docs/04](docs/04-engineering-feasibility.md) | 评估者、架构师、团队负责人、实施者 | 方法论差异、机制解剖、协作模式、工程化可行性 |
| [docs/guide/00-使用指引.md](docs/guide/00-使用指引.md) | 使用方 | 使用指引（人话版）：六篇短文，把上游 00–18 讲明白 |
| [docs/guide/01](docs/guide/01-第一次跑起来.md)、[docs/guide/02](docs/guide/02-先认词.md) | 使用方 | 第一次跑起来 / 先认词：intent、阶段、档位 |
| [docs/06](docs/06-aidlc-vs-openspec.md) | 选型者、架构师 | AI-DLC 与 OpenSpec 的逐维度对照、组合方案与选型判据 |

## 项目 `.gitignore`

```gitignore
# AI-DLC 每用户运行时状态（会话绑定、用量账本）
aidlc/.aidlc-sessions/

# 引擎运行时暂存（锁、恢复面包屑、评审基线），可再生成
**/.aidlc-engine/
```

`.agents/` 建议提交进版本库，团队共用一份引擎，每个成员只需要装 Bun。`aidlc/` 下的工作产物按项目规范决定提交还是忽略，只有 `.aidlc-sessions/` 明确属于每用户运行时状态，不该进版本库。

## 常见问题

| 问题 | 处理 |
| --- | --- |
| Windows 上 `bun` 报 `系统找不到指定的路径` | 命中了 npm 残留 shim，见上文前置条件与 [usage-guide.md](usage-guide.md) 第 1 节 |
| 引擎报找不到 `aidlc.ts` 或路径错误 | `.agents` 放错层级或改了名，必须在项目根且名字就是 `.agents`，见 [usage-guide.md](usage-guide.md) 第 2 节 |
| 审批门反复拒绝，提示缺人类轮次 | 会话记账没执行。本发行版没有 hook 系统，记账由 conductor 按技能里的 `## Host duties` 执行，见 [usage-guide.md](usage-guide.md) 第 8 与第 9 节 |
| `--doctor` 报 warn 或 fail | 它按默认发行版口径检查根文件，例如 `.claude/settings.json` 与 `CLAUDE.md`，本发行版刻意不提供。实测退出码 1、两条 fail 六条 warn，而 `Framework integrity` 的 12 项全通过，不影响引擎，见 [usage-guide.md](usage-guide.md) 第 7 节 |