ai-dev-requirements 0.3.0 → 0.4.0

package/README.md

@@ -10,9 +10,9 @@ An agent harness workflow for AI coding tools, enabling controlled requirement i
 
 | Deliverable | Description |
 |-------------|-------------|
-| **Requirements MCP Server** (`src/`) | MCP server for ONES work items. Routes 需求/任务/缺陷 by `issueType.detailType`. |
+| **Requirements MCP Server** (`src/`) | MCP server for ONES work items. Routes requirements, tasks, and defects by `issueType.detailType`. |
 | **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. |
-| **Grill-me Skills** (`skills/grill-me/`, `skills/grilling/`) | Interview loop for open product decisions. Uses `get_grilling_brief`; does not live in the MCP server. |
+| **Grill-me Skills** (`skills/grill-me/`, `skills/grilling/`) | Fact-first interview entry and decision-tree primitive for ambiguous development requests. ONES sources use one `get_grilling_brief` call. |
 
 ---
 
@@ -36,11 +36,11 @@ Once installed, AI coding tools will automatically use the dev-workflow harness
 
 Codex loads skills from `$CODEX_HOME/skills`. If `CODEX_HOME` is not set, the default is `~/.codex`.
 
-From this repository:
+From this repository, install all three cooperating skills:
 
 ```bash
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
-cp -R skills/dev-workflow/* "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow/"
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/dev-workflow skills/grill-me skills/grilling "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
 For local development, use a symlink instead so Codex picks up edits from this checkout after restart:
@@ -48,6 +48,8 @@ For local development, use a symlink instead so Codex picks up edits from this c
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 ln -s "$(pwd)/skills/dev-workflow" "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+ln -s "$(pwd)/skills/grill-me" "${CODEX_HOME:-$HOME/.codex}/skills/grill-me"
+ln -s "$(pwd)/skills/grilling" "${CODEX_HOME:-$HOME/.codex}/skills/grilling"
 ```
 
 Restart Codex after installing or updating the skill.
@@ -76,12 +78,12 @@ When the harness is active, the agent should announce:
 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.
+Requirement-driven work has two non-bypassable approval gates: approve the current user stories before planning, then approve the current implementation plan after coverage validation passes. Mechanical tasks with an obvious bounded result do not need to trigger the full harness.
 
 Expected flow:
 
 ```text
-Intake -> Context Load -> Normalize -> Harness Plan -> Coverage Validation -> Gated Execution -> Verification -> Review -> Handoff
+Context -> Grill -> User Stories -> Stories Approval -> Plan -> Coverage Validation -> Plan Approval -> Execution -> Verification -> Review -> Handoff
 ```
 
 ### 4. Install MCP Server (Optional)
@@ -104,6 +106,10 @@ Create `.requirements-mcp.json` in your project root:
         "type": "ones-pkce",
         "emailEnv": "ONES_ACCOUNT",
         "passwordEnv": "ONES_PASSWORD"
+      },
+      "openApiAuth": {
+        "type": "token",
+        "tokenEnv": "ONES_OPENAPI_TOKEN"
       }
     }
   },
@@ -121,13 +127,19 @@ Add to your `.mcp.json`:
       "args": ["ai-dev-requirements"],
       "env": {
         "ONES_ACCOUNT": "${ONES_ACCOUNT}",
-        "ONES_PASSWORD": "${ONES_PASSWORD}"
+        "ONES_PASSWORD": "${ONES_PASSWORD}",
+        "ONES_OPENAPI_TOKEN": "${ONES_OPENAPI_TOKEN}"
       }
     }
   }
 }
 ```
 
+`openApiAuth` is optional and independent from the internal `ones-pkce` product
+session. It is used for documented Wiki metadata and search requests when
+available. Wiki creates and updates always use the product session plus the live
+JSONv1 collaboration protocol, so they do not require a Personal API Key.
+
 #### MCP security boundaries
 
 - ONES titles, descriptions, test cases, and attachment metadata are marked as untrusted data. Instructions embedded in them must never drive tool calls.
@@ -174,7 +186,7 @@ Requirements are not limited to ONES. Pair with official MCP servers for GitHub
 A self-contained AI-assisted agent harness skill that governs the full development lifecycle:
 
 ```
-Intake -> Context Load -> Normalize -> Harness Plan -> Coverage Validation -> Gated Execution -> Verification -> Review -> Handoff
+Context -> Grill -> User Stories -> Stories Approval -> Plan -> Coverage Validation -> Plan Approval -> 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.
@@ -186,6 +198,7 @@ skills/dev-workflow/
 ├── SKILL.md                         # Skill entry (YAML frontmatter + harness definition)
 └── references/
     ├── workflow.md                  # Agent harness lifecycle
+    ├── requirement-validation.md    # Coverage validation gate contract
     ├── 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
@@ -204,7 +217,7 @@ skills/dev-workflow/
 ```
 ai-dev-workflow/
 ├── skills/
-│   ├── grill-me/                    # User-invoked grilling entry
+│   ├── grill-me/                    # Ambiguity-resolution entry
 │   ├── grilling/                    # Interview primitive
 │   └── dev-workflow/                # Agent Harness Workflow Skill
 │
@@ -274,7 +287,7 @@ pnpm build
 pnpm test
 
 # Type check
-pnpm lint
+pnpm typecheck
 ```
 
 

package/README.zh-CN.md

@@ -12,7 +12,7 @@
 |-------|------|
 | **Requirements MCP Server** (`src/`) | 需求获取 MCP 服务。按 `issueType.detailType` 区分需求 / 任务 / 缺陷。 |
 | **Agent Harness Workflow Skill** (`skills/dev-workflow/`) | 自包含的 AI agent harness 工作流 Skill，安装后即可跑通需求接入、计划、门禁执行、验证、审查和交付。 |
-| **Grill-me Skills** (`skills/grill-me/`, `skills/grilling/`) | 开工前访谈循环。先调 `get_grilling_brief`；访谈本身不进 MCP Server。 |
+| **Grill-me Skills** (`skills/grill-me/`, `skills/grilling/`) | 面向模糊开发需求的事实优先访谈入口和决策树原语；ONES 来源只调用一次 `get_grilling_brief`。 |
 
 ---
 
@@ -36,11 +36,11 @@ npx skills add daguanren21/ai-dev-workflow -a claude-code
 
 Codex 从 `$CODEX_HOME/skills` 加载 skills。未设置 `CODEX_HOME` 时，默认目录是 `~/.codex`。
 
-从当前仓库安装：
+从当前仓库安装三个配套 skill：
 
 ```bash
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
-cp -R skills/dev-workflow/* "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow/"
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/dev-workflow skills/grill-me skills/grilling "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
 如果是在本地开发这个 skill，建议使用软链接，这样更新当前仓库后重启 Codex 即可生效：
@@ -48,6 +48,8 @@ cp -R skills/dev-workflow/* "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow/"
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 ln -s "$(pwd)/skills/dev-workflow" "${CODEX_HOME:-$HOME/.codex}/skills/dev-workflow"
+ln -s "$(pwd)/skills/grill-me" "${CODEX_HOME:-$HOME/.codex}/skills/grill-me"
+ln -s "$(pwd)/skills/grilling" "${CODEX_HOME:-$HOME/.codex}/skills/grilling"
 ```
 
 安装或更新后需要重启 Codex。
@@ -76,12 +78,12 @@ Harness 生效时，agent 应该先声明：
 I'm using the dev-workflow harness to drive this development task.
 ```
 
-默认情况下，harness 会先生成 user stories 和 implementation plan，然后暂停等待确认，再开始写代码。你不需要每次重复“先写计划再实现”。只有想跳过这个门禁时，才需要明确说明。
+需求驱动开发包含两个不可跳过的确认门禁：先确认当前 user stories，再生成 implementation plan；覆盖校验通过后，再确认当前 plan 才能开始实现。结果明确且范围很小的机械任务不需要触发完整 harness。
 
 预期流程：
 
 ```text
-需求接入 → 上下文加载 → 需求规范化 → Harness 计划 → 覆盖校验 → 门禁执行 → 验证 → 审查 → 交付
+上下文 → Grill → User Stories → Stories 确认 → Plan → 覆盖校验 → Plan 确认 → 实现 → 验证 → 审查 → 交付
 ```
 
 ### 4. 安装 MCP Server（可选）
@@ -174,7 +176,7 @@ npm install -g ai-dev-requirements
 自包含的 AI 辅助 agent harness 工作流 Skill，安装后自动管控完整开发生命周期：
 
 ```
-需求接入 → 上下文加载 → 需求规范化 → Harness 计划 → 覆盖校验 → 门禁执行 → 验证 → 审查 → 交付
+上下文 → Grill → User Stories → Stories 确认 → Plan → 覆盖校验 → Plan 确认 → 实现 → 验证 → 审查 → 交付
 ```
 
 这个 harness 遵循“前馈 + 反馈”模型：先用计划、产物和任务边界引导 agent，再用 lint、typecheck、build、tests、review 等确定性门禁形成反压，合格后再交付。
@@ -186,6 +188,7 @@ skills/dev-workflow/
 ├── SKILL.md                         # Skill 入口（YAML frontmatter + harness 定义）
 └── references/
     ├── workflow.md                  # Agent harness 生命周期
+    ├── requirement-validation.md    # 覆盖校验门禁规范
     ├── task-types.md                # Harness 任务类型、调度模式、声明语法
     ├── service-transform.md         # Service 层 Transform 适配模式
     └── templates/                   # 任务声明模板
@@ -204,7 +207,7 @@ skills/dev-workflow/
 ```
 ai-dev-workflow/
 ├── skills/
-│   ├── grill-me/                    # 用户入口
+│   ├── grill-me/                    # 模糊需求处理入口
 │   ├── grilling/                    # 访谈原语
 │   └── dev-workflow/                # Agent Harness Workflow Skill
 ├── src/                             # Requirements MCP Server 源码
@@ -273,7 +276,7 @@ pnpm build
 pnpm test
 
 # 类型检查
-pnpm lint
+pnpm typecheck
 ```