ai-dev-requirements 0.1.8 → 0.1.10

package/README.md

@@ -2,7 +2,7 @@
 
 [中文](./README.zh-CN.md)
 
-A parallel-task development framework for AI coding tools, enabling end-to-end development workflow automation.
+An agent harness workflow for AI coding tools, enabling controlled requirement intake, planning, gated execution, verification, review, and handoff.
 
 ---
 
@@ -11,13 +11,13 @@ A parallel-task development framework for AI coding tools, enabling end-to-end d
 | Deliverable | Description |
 |-------------|-------------|
 | **Requirements MCP Server** (`src/`) | MCP server for fetching requirements, with built-in ONES adapter. Installable via npm. |
-| **Dev Workflow Skill** (`skills/dev-workflow/`) | Self-contained development workflow skill. Install it and run the full process. |
+| **Agent Harness Workflow Skill** (`skills/dev-workflow/`) | Self-contained agent harness skill. Install it to run requirement intake, planning, gated execution, verification, review, and handoff. |
 
 ---
 
 ## Quick Start
 
-### 1. Install Dev Workflow Skill
+### 1. Install Agent Harness Workflow Skill
 
 ```bash
 npx skills add daguanren21/ai-dev-workflow
@@ -29,9 +29,61 @@ Install to a specific agent with `-a`:
 npx skills add daguanren21/ai-dev-workflow -a claude-code
 ```
 
-Once installed, AI coding tools will automatically use the dev-workflow skill to drive the full development process.
+Once installed, AI coding tools will automatically use the dev-workflow harness to govern the full development process.
 
-### 2. Install MCP Server (Optional)
+### 2. Install For Codex
+
+Codex loads skills from `$CODEX_HOME/skills`. If `CODEX_HOME` is not set, the default is `~/.codex`.
+
+From this repository:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+cp -R skills/dev-workflow/* "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow/"
+```
+
+For local development, use a symlink instead so Codex picks up edits from this checkout after restart:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+ln -s "$(pwd)/skills/dev-workflow" "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+```
+
+Restart Codex after installing or updating the skill.
+
+### 3. Trigger The Harness
+
+The skill can be triggered automatically when the task looks like AI-assisted development work: requirement intake, issue implementation, task planning, gated execution, verification, review, or handoff.
+
+You can also trigger it explicitly:
+
+```text
+Use the dev-workflow harness to implement this requirement: <requirement text or ticket id>
+```
+
+```text
+Use the dev-workflow harness. Read ONES-123, write the plan first, then wait for confirmation before implementation.
+```
+
+```text
+Use the dev-workflow harness for this GitHub issue: <issue url>
+```
+
+When the harness is active, the agent should announce:
+
+```text
+I'm using the dev-workflow harness to drive this development task.
+```
+
+By default, the harness generates user stories and an implementation plan before writing code, then pauses for confirmation. You do not need to repeat "write the plan first" in every prompt. Say so only when you want to bypass that gate.
+
+Expected flow:
+
+```text
+Intake -> Context Load -> Normalize -> Harness Plan -> Coverage Validation -> Gated Execution -> Verification -> Review -> Handoff
+```
+
+### 4. Install MCP Server (Optional)
 
 If you use ONES for requirement management:
 
@@ -75,7 +127,7 @@ Add to your `.mcp.json`:
 }
 ```
 
-### 3. Add Companion MCP Servers (Optional)
+### 5. Add Companion MCP Servers (Optional)
 
 Requirements are not limited to ONES. Pair with official MCP servers for GitHub / Jira / Figma:
 
@@ -108,22 +160,24 @@ Requirements are not limited to ONES. Pair with official MCP servers for GitHub
 
 ---
 
-## Dev Workflow Skill
+## Agent Harness Workflow Skill
 
-A self-contained AI-assisted development workflow skill that drives 7 phases:
+A self-contained AI-assisted agent harness skill that governs the full development lifecycle:
 
 ```
-Requirements → User Stories → UI Resources → Skill Matching → Implementation Plan → Code → Verification
+Intake -> Context Load -> Normalize -> Harness Plan -> Coverage Validation -> Gated Execution -> Verification -> Review -> Handoff
 ```
 
+The harness follows a feedforward + feedback model: it guides the agent with plans, artifacts, and task boundaries, then uses deterministic gates such as lint, typecheck, build, tests, and review as backpressure before handoff.
+
 Skill directory structure:
 
 ```
 skills/dev-workflow/
-├── SKILL.md                         # Skill entry (YAML frontmatter + workflow definition)
+├── SKILL.md                         # Skill entry (YAML frontmatter + harness definition)
 └── references/
-    ├── workflow.md                  # 10-step end-to-end workflow
-    ├── task-types.md                # Task types, scheduling strategies, declaration syntax
+    ├── workflow.md                  # Agent harness lifecycle
+    ├── task-types.md                # Harness task types, scheduler modes, declaration syntax
     ├── service-transform.md         # Service-layer transform pattern for Mock/API adaptation
     └── templates/                   # Task declaration templates
         ├── code-dev-task.md
@@ -140,10 +194,10 @@ skills/dev-workflow/
 
 ```
 ai-dev-workflow/
-├── skills/dev-workflow/             # Dev Workflow Skill (self-contained)
+├── skills/dev-workflow/             # Agent Harness Workflow Skill (self-contained)
 │   ├── SKILL.md
 │   └── references/
-│       ├── workflow.md
+│       ├── workflow.md              # Agent harness lifecycle
 │       ├── task-types.md
 │       ├── service-transform.md
 │       └── templates/

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](./README.md)
 
-一套面向 AI 编码工具的并行任务开发框架，实现端到端的开发工作流自动化。
+一套面向 AI 编码工具的 agent harness 工作流，用于管控需求接入、计划、门禁执行、验证、审查和交付。
 
 ---
 
@@ -11,13 +11,13 @@
 | 交付物 | 说明 |
 |-------|------|
 | **Requirements MCP Server** (`src/`) | 需求获取 MCP 服务，内置 ONES 适配器，可通过 npm 安装 |
-| **Dev Workflow Skill** (`skills/dev-workflow/`) | 自包含的开发工作流 Skill，安装后即可跑通完整流程 |
+| **Agent Harness Workflow Skill** (`skills/dev-workflow/`) | 自包含的 AI agent harness 工作流 Skill，安装后即可跑通需求接入、计划、门禁执行、验证、审查和交付。 |
 
 ---
 
 ## 快速开始
 
-### 1. 安装 Dev Workflow Skill
+### 1. 安装 Agent Harness Workflow Skill
 
 ```bash
 npx skills add daguanren21/ai-dev-workflow
@@ -29,9 +29,61 @@ npx skills add daguanren21/ai-dev-workflow
 npx skills add daguanren21/ai-dev-workflow -a claude-code
 ```
 
-安装后，AI 编码工具会自动识别并使用 dev-workflow skill 驱动完整的开发流程。
+安装后，AI 编码工具会自动识别并使用 dev-workflow harness 管控完整开发流程。
 
-### 2. 安装 MCP Server（可选）
+### 2. 安装到 Codex
+
+Codex 从 `$CODEX_HOME/skills` 加载 skills。未设置 `CODEX_HOME` 时，默认目录是 `~/.codex`。
+
+从当前仓库安装：
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+cp -R skills/dev-workflow/* "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow/"
+```
+
+如果是在本地开发这个 skill，建议使用软链接，这样更新当前仓库后重启 Codex 即可生效：
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+ln -s "$(pwd)/skills/dev-workflow" "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+```
+
+安装或更新后需要重启 Codex。
+
+### 3. 触发 Harness
+
+当任务看起来是 AI 辅助开发工作时，skill 可以自动触发，例如：需求接入、issue 实现、任务规划、门禁执行、验证、审查或交付。
+
+也可以显式触发：
+
+```text
+使用 dev-workflow harness 实现这个需求：<需求文本或工单号>
+```
+
+```text
+使用 dev-workflow harness。读取 ONES-123，先写计划，确认后再实现。
+```
+
+```text
+使用 dev-workflow harness 处理这个 GitHub issue：<issue url>
+```
+
+Harness 生效时，agent 应该先声明：
+
+```text
+I'm using the dev-workflow harness to drive this development task.
+```
+
+默认情况下，harness 会先生成 user stories 和 implementation plan，然后暂停等待确认，再开始写代码。你不需要每次重复“先写计划再实现”。只有想跳过这个门禁时，才需要明确说明。
+
+预期流程：
+
+```text
+需求接入 → 上下文加载 → 需求规范化 → Harness 计划 → 覆盖校验 → 门禁执行 → 验证 → 审查 → 交付
+```
+
+### 4. 安装 MCP Server（可选）
 
 如果使用 ONES 进行需求管理：
 
@@ -75,7 +127,7 @@ npm install -g ai-dev-requirements
 }
 ```
 
-### 3. 搭配其他 MCP Server（可选）
+### 5. 搭配其他 MCP Server（可选）
 
 需求不限于 ONES，可搭配官方 MCP Server 获取 GitHub / Jira / Figma 资源：
 
@@ -108,22 +160,24 @@ npm install -g ai-dev-requirements
 
 ---
 
-## Dev Workflow Skill
+## Agent Harness Workflow Skill
 
-自包含的 AI 辅助开发工作流 Skill，安装后自动驱动 7 个阶段：
+自包含的 AI 辅助 agent harness 工作流 Skill，安装后自动管控完整开发生命周期：
 
 ```
-需求获取 → 用户故事 → UI 资源获取 → 技能匹配 → 实现计划 → 代码实现 → 验证
+需求接入 → 上下文加载 → 需求规范化 → Harness 计划 → 覆盖校验 → 门禁执行 → 验证 → 审查 → 交付
 ```
 
+这个 harness 遵循“前馈 + 反馈”模型：先用计划、产物和任务边界引导 agent，再用 lint、typecheck、build、tests、review 等确定性门禁形成反压，合格后再交付。
+
 Skill 目录结构：
 
 ```
 skills/dev-workflow/
-├── SKILL.md                         # Skill 入口（YAML frontmatter + 工作流定义）
+├── SKILL.md                         # Skill 入口（YAML frontmatter + harness 定义）
 └── references/
-    ├── workflow.md                  # 10 步端到端工作流
-    ├── task-types.md                # 任务类型、调度策略、声明语法
+    ├── workflow.md                  # Agent harness 生命周期
+    ├── task-types.md                # Harness 任务类型、调度模式、声明语法
     ├── service-transform.md         # Service 层 Transform 适配模式
     └── templates/                   # 任务声明模板
         ├── code-dev-task.md
@@ -140,10 +194,10 @@ skills/dev-workflow/
 
 ```
 ai-dev-workflow/
-├── skills/dev-workflow/             # Dev Workflow Skill（自包含工作流）
+├── skills/dev-workflow/             # Agent Harness Workflow Skill（自包含工作流）
 │   ├── SKILL.md
 │   └── references/
-│       ├── workflow.md
+│       ├── workflow.md              # Agent harness 生命周期
 │       ├── task-types.md
 │       ├── service-transform.md
 │       └── templates/