harness-async 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Junhao Zhuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# harness-async
+
+`harness-async` 是 `ha`（harness-agent）的设计与规划仓库。项目目标是构建一个 Agent-first 的 CLI 工具和本地 Web Dashboard，用于支持人类与多个 agent 之间的异步分层协作。
+
+当前仓库同时承载两类资产：
+
+- 设计文档：架构、MVP、路线图和 phase 计划。
+- 可运行实现：TypeScript CLI、守护进程、Dashboard 和测试。
+
+设计文档仍然是项目共识来源，但仓库已经不再只是规划稿。
+
+## 项目要解决的问题
+
+项目希望把复杂工作拆成可编排、可追踪、可回溯的任务流，让人类只在真正需要介入时介入，把更多执行工作交给 agent。
+
+核心设计围绕以下几点展开：
+
+- Agent-first：CLI 的主要用户是 agent，不是人。
+- 分层协作：任务按 L1、L2、L3 区分自治执行、人工监督和人工主导。
+- DAG 编排：任务之间可以声明依赖关系，支持解锁、调度和可视化。
+- 双层存储：同时支持项目级任务和全局级任务。
+- 可视化与审计：通过 Dashboard、事件日志和运行记录追踪全过程。
+
+## 当前状态
+
+仓库当前已经包含可运行的 `ha` 原型实现，覆盖任务管理、
+守护进程、Dashboard、`ha run` 和对应测试。文档与规格仍然需要和
+实现保持同步，因此阅读代码前仍然建议先看 `docs/` 与 `specs/`。
+
+现有文档覆盖了以下主题：
+
+- 架构设计：定义系统边界、存储模型、CLI 设计和核心数据结构。
+- MVP 定义：明确第一阶段做什么、不做什么，以及关键用户流程。
+- Roadmap：拆分 Phase 0 到 Phase 3 的演进路径和关键技术决策。
+- Phase 计划：把每个阶段进一步细化为可执行任务列表和验收标准。
+
+## 仓库结构
+
+仓库当前以文档为主，目录职责如下：
+
+```text
+.
+├── docs/
+│   ├── 01-architecture.md
+│   ├── 02-mvp.md
+│   └── 03-roadmap.md
+├── specs/
+│   ├── AGENTS.md
+│   └── active/
+│       ├── phase0-scaffold-plan.md
+│       ├── phase1-mvp-plan.md
+│       └── phase2-agent-integration-plan.md
+└── LICENSE
+```
+
+- `docs/`：项目级设计文档，回答"这是什么、为什么这样设计、计划怎么演进"。
+- `specs/`：实施计划和工作规范，回答"接下来按什么顺序落地、每一步如何验收"。
+- `specs/AGENTS.md`：只约束 `specs/` 目录内设计与计划文档的编写规范。
+- `LICENSE`：开源许可。
+
+后续如果开始实现，预计会新增实际代码目录，例如 `ha/`、`src/`、`skills/` 或其他运行时相关结构。
+
+## 安装与试用
+
+如果你只想在本机试用 `ha` CLI，先确保本地环境满足 Node.js 20+
+和 npm 10+。这个项目发布后的命令名是 `ha`，包名是
+`harness-async`。
+
+本地开发安装：
+
+```bash
+npm install
+npm run build
+npm link
+ha --help
+```
+
+全局安装已发布版本：
+
+```bash
+npm install -g harness-async
+ha init
+ha doctor
+```
+
+免全局安装的临时运行方式：
+
+```bash
+npx -y -p harness-async ha init
+npx -y -p harness-async ha doctor
+```
+
+如果你希望命令写成 `npx ha@latest ...`，那需要 npm 上存在名为
+`ha` 的包，或者改成你自己的 scope 包名，例如 `@your-scope/ha`。
+
+## 发布到 npm
+
+如果你要把这个 CLI 发布给别人安装，先确认构建、测试和打包都通过。
+当前仓库已经配置了 `prepublishOnly`，执行 `npm publish` 前会自动跑
+构建和测试。
+
+最小发布流程：
+
+```bash
+npm login
+npm publish
+```
+
+发布前建议先做一次本地打包检查：
+
+```bash
+npm run build
+npm pack --dry-run
+```
+
+发布后可用下面的命令验证：
+
+```bash
+npm install -g harness-async
+ha --help
+ha init
+```
+
+## 建议阅读顺序
+
+如果你是第一次接触这个仓库，建议按下面顺序阅读：
+
+1. 阅读 [`docs/01-architecture.md`](docs/01-architecture.md)，理解项目定位、核心架构和关键设计选择。
+2. 阅读 [`docs/02-mvp.md`](docs/02-mvp.md)，了解 MVP 范围、优先级和典型用户流程。
+3. 阅读 [`docs/03-roadmap.md`](docs/03-roadmap.md)，建立阶段性认知和技术决策上下文。
+4. 根据当前工作目标，进入 `specs/active/` 阅读对应 phase 的计划文档。
+
+## 文档与计划的关系
+
+这个仓库中的文档分为两层：
+
+- `docs/` 记录稳定的产品与架构共识。
+- `specs/active/` 记录可执行的阶段性实施计划。
+
+如果后续发生设计变化，通常需要先更新 `docs/`，再同步更新关联的 `specs/` 文档，避免计划与架构描述脱节。
+
+## 适合谁使用
+
+这个仓库主要服务三类读者：
+
+- 设计实现 `ha` 的开发者和 agent。
+- 需要理解产品边界和技术路线的协作者。
+- 未来会为 `ha` 编写 skill、adapter 或 dashboard 的贡献者。
+
+## 下一步
+
+下一阶段的自然工作是根据 `specs/active/` 中的计划启动脚手架实现，并在实现过程中持续把设计、计划和代码保持同步。