ai-dev-requirements 0.1.9 → 0.1.10

package/skills/dev-workflow/references/task-types.md

@@ -1,123 +1,174 @@
-# Task Types & Scheduling
+# Harness Task Types & Scheduler
+
+Task types are scheduling primitives for the agent harness. They define how work may run, what isolation is required, and what review level applies before handoff.
 
 ## Task Types
 
-| Type | ID | Strategy | Review Level | Description |
-|------|-----|---------|------------|------|
-| Code Development | `code:dev` | `isolated` | strict | Serial within module, parallel across modules |
-| Code Fix | `code:fix` | `isolated` | standard | Serial within file |
-| Code Refactor | `code:refactor` | `serial` | strict | Global serial, large impact |
-| Doc Writing | `doc:write` | `parallel` | light | Fully parallel |
-| Doc Translation | `doc:translate` | `parallel` | light | Fully parallel |
-| Research | `research` | `parallel` | light | Fully parallel, supports caching |
-| Data Processing | `data` | `isolated` | standard | Isolated by data source |
-| Testing | `test` | `parallel` | standard | Fully parallel |
+| Type | ID | Scheduler | Review Level | Harness Use |
+|------|----|-----------|--------------|-------------|
+| Code Development | `code:dev` | `isolated` | strict | New behavior in a bounded module or feature area |
+| Code Fix | `code:fix` | `isolated` | standard | Defect correction owned by a file, module, or failing gate |
+| Code Refactor | `code:refactor` | `serial` | strict | Structure change with broad impact or shared contracts |
+| Doc Writing | `doc:write` | `parallel` | light | New or updated documentation artifacts |
+| Doc Translation | `doc:translate` | `parallel` | light | Translation work that preserves source meaning |
+| Research | `research` | `parallel` | light | Context gathering, option comparison, or source analysis |
+| Data Processing | `data` | `isolated` | standard | Fixture, migration, import, export, or data-source work |
+| Testing | `test` | `parallel` | standard | Unit, integration, regression, or verification work |
 
-## Scheduling Strategies
+## Scheduler Modes
 
-- **parallel** — Fully parallel, no restrictions (bounded by parallel_limit)
-- **isolated** — Group by isolation key; serial within group, parallel between groups
-- **serial** — Global lock, one task at a time
+| Scheduler | Rule | Use When |
+|-----------|------|----------|
+| `parallel` | Tasks may run concurrently up to `parallel_limit` | Work touches independent artifacts |
+| `isolated` | Tasks sharing an isolation key run serially; different keys may run concurrently | Work is safe across modules but unsafe inside the same module or file |
+| `serial` | One task runs at a time under a global lock | Work changes shared contracts, architecture, or broad behavior |
 
-## Max Parallelism: 5
+Default `parallel_limit`: 5.
 
 ## Task Declaration Syntax
 
 ```markdown
-## TaskGroup: <group name>
-
-### Meta
-- parallel_limit: 5
-- review_level: standard
-- on_failure: continue | stop
-
-### Tasks
-1. [code:dev] Implement auth module @isolated(auth/)
-2. [code:dev] Implement order module @isolated(order/)
-3. [doc:write] Write API docs
-4. [research] Research payment gateway @cache(7d)
+## HarnessTask: <task id> - <task name>
+
+### Control
+- type: code:dev | code:fix | code:refactor | doc:write | doc:translate | research | data | test
+- agent_role: implementer | reviewer | researcher | tester | documenter
+- scheduler: parallel | isolated | serial
+- isolation_key: <module-or-file-path>
+- dependencies: []
+- review_level: light | standard | strict
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
+
+### Inputs
+- Requirement: <requirement id or story id>
+- Context: <artifact path or MCP source>
+
+### Outputs
+- Artifact: <file path>
+- Verification: <command or review gate>
+
+### Done When
+- <observable completion condition>
 ```
 
-| Element | Format | Description |
-|---------|--------|-------------|
-| Task type | `[type:subtype]` | Type identifier in brackets |
-| Isolation key | `@isolated(key)` | Grouping key for isolation |
-| Cache | `@cache(duration)` | Cache TTL for research tasks |
-| Dependency | `@depends(task_id)` | Prerequisite task dependency |
+## Control Fields
 
-## Fullstack Parallel Strategy
+| Field | Required | Meaning |
+|-------|:---:|---------|
+| `type` | Yes | Work category and default review expectation |
+| `agent_role` | Yes | Primary role responsible for the task |
+| `scheduler` | Yes | Execution mode: `parallel`, `isolated`, or `serial` |
+| `isolation_key` | Yes for `isolated`, optional for others | Module, file, data source, or shared contract boundary |
+| `dependencies` | Yes | Task IDs that must finish first; use an empty list when none exist |
+| `review_level` | Yes | `light`, `standard`, or `strict` |
+| `feedback_mode` | Yes | How verification output is exposed to the agent |
+| `retry_limit` | Yes | Maximum repair attempts before human escalation |
 
-```
-     ┌─────────────┐
-     │ API Contract │
-     └──────┬──────┘
-            ↓
-  ┌─────────┴─────────┐
-  ↓                   ↓
-┌─────────┐     ┌─────────┐
-│ Frontend │     │ Backend │
-│ (Mock)  │     │ (API)   │
-└────┬────┘     └────┬────┘
-     └────────┬──────┘
-              ↓
-       ┌─────────────┐
-       │ Integration  │
-       └─────────────┘
-```
+## Review Levels
 
-## Templates
+| Level | Applies To | Required Review |
+|-------|------------|-----------------|
+| `light` | Documentation, research, low-risk metadata | Check accuracy, links, scope, and consistency |
+| `standard` | Fixes, tests, data work, bounded behavior | Check correctness, regression risk, and verification evidence |
+| `strict` | New features, refactors, shared contracts | Check requirements coverage, architecture, edge cases, and full verification gates |
 
-### Code Development
-```markdown
-## TaskGroup: [Feature Name]
-### Meta
-- parallel_limit: 5
-- review_level: strict
-- on_failure: continue
-### Tasks
-1. [code:dev] Implement [module] core logic @isolated([module]/)
-2. [code:dev] Implement [module] UI components @isolated([module]/)
-3. [code:dev] Implement [module] API layer @isolated([module]/api/)
-4. [test] Write [module] unit tests @isolated([module]/)
-```
+## Backpressure
+
+Verification output should act as backpressure:
+
+- `quiet_success`: passing gates report only the gate name and pass status.
+- `actionable_failure`: failing gates expose the command, key error, likely owner task, and repair instruction.
+- Prefer targeted gates before full gates to keep feedback fast and relevant.
+- Default `retry_limit` is 2 repair attempts before human escalation.
+- Long logs belong in `execution-log.md`, not in the active agent context.
+
+## Scheduling Examples
+
+### Independent Documentation
 
-### Code Fix
 ```markdown
-## TaskGroup: [Bug Description]
-### Meta
-- parallel_limit: 3
-- review_level: standard
-- on_failure: stop
-### Tasks
-1. [research] Root cause analysis @cache(1d)
-2. [code:fix] Fix [bug] @isolated([file_path])
-3. [test] Add regression tests @isolated([file_path])
+## HarnessTask: HT-DOC-1 - Update README quick start
+
+### Control
+- type: doc:write
+- agent_role: documenter
+- scheduler: parallel
+- isolation_key: docs/readme
+- dependencies: []
+- review_level: light
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
+
+### Inputs
+- Requirement: US-DOC-1
+- Context: docs/plans/harness/requirements.md
+
+### Outputs
+- Artifact: README.md
+- Verification: content review plus `pnpm lint`
+
+### Done When
+- README describes the current harness lifecycle and no stale public workflow wording remains.
 ```
 
-### Code Refactor
+### Isolated Feature Work
+
 ```markdown
-## TaskGroup: [Refactor Goal]
-### Meta
-- parallel_limit: 1
+## HarnessTask: HT-FEAT-1 - Implement requirement search filter
+
+### Control
+- type: code:dev
+- agent_role: implementer
+- scheduler: isolated
+- isolation_key: src/tools/search-requirements.ts
+- dependencies: [HT-PLAN-1]
 - review_level: strict
-- on_failure: stop
-### Tasks
-1. [research] Analyze dependencies
-2. [code:refactor] Refactor core structure
-3. [code:fix] Fix type errors from refactoring
-4. [test] Run full test suite
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
+
+### Inputs
+- Requirement: US-2
+- Context: docs/plans/search-filter/user-stories.md
+
+### Outputs
+- Artifact: src/tools/search-requirements.ts
+- Verification: `pnpm test:run tests/tools/search-requirements.test.ts`
+
+### Done When
+- Search accepts the new filter, preserves existing behavior, and targeted tests pass.
 ```
 
-### Research
+### Serial Refactor
+
 ```markdown
-## TaskGroup: [Research Topic]
-### Meta
-- parallel_limit: 5
-- review_level: light
-- on_failure: continue
-### Tasks
-1. [research] Research [option A] @cache(7d)
-2. [research] Research [option B] @cache(7d)
-3. [research] Compare A and B @depends(1,2)
-4. [doc:write] Write conclusion document
+## HarnessTask: HT-REF-1 - Split adapter factory responsibilities
+
+### Control
+- type: code:refactor
+- agent_role: implementer
+- scheduler: serial
+- isolation_key: global
+- dependencies: [HT-COVERAGE-1]
+- review_level: strict
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
+
+### Inputs
+- Requirement: US-REF-1
+- Context: docs/plans/adapter-refactor/implementation-plan.md
+
+### Outputs
+- Artifact: src/adapters/
+- Verification: `pnpm test:run && pnpm typecheck && pnpm build`
+
+### Done When
+- Public adapter behavior is unchanged, contracts remain typed, and full verification gates pass.
 ```
+
+## Failure Handling
+
+- If a `parallel` task conflicts with another task, stop both tasks and reclassify the boundary as `isolated`.
+- If an `isolated` task conflicts within the same key, serialize that key and continue other keys.
+- If a `serial` task fails, stop the harness and resolve the failure before scheduling more work.
+- If verification is unavailable, record the reason and ask for confirmation before handoff.

package/skills/dev-workflow/references/templates/code-dev-task.md

@@ -1,29 +1,42 @@
-# 代码开发任务模板
+# Code Development Harness Task Template
 
-```markdown
-## TaskGroup: [功能名称]
+## HarnessTask: HT-DEV-1 - Implement Feature Module
 
-### Meta
-- parallel_limit: 5
+### Control
+- type: code:dev
+- agent_role: implementer
+- scheduler: isolated
+- isolation_key: src/<module>/
+- dependencies: []
 - review_level: strict
-- on_failure: continue
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [code:dev] 实现 [模块名] 核心逻辑 @isolated([module]/)
-2. [code:dev] 实现 [模块名] UI 组件 @isolated([module]/)
-3. [code:dev] 实现 [模块名] API 接口层 @isolated([module]/api/)
-4. [test] 编写 [模块名] 单元测试 @isolated([module]/)
-```
+### Inputs
+- Requirement: US-<number>
+- Context: docs/plans/<feature-name>/user-stories.md
+- Plan: docs/plans/<feature-name>/implementation-plan.md
 
-## 使用说明
+### Steps
+- Write or update the failing test that captures the acceptance criterion.
+- Run the targeted test and record the failure.
+- Implement the smallest production change inside the isolation key.
+- Run the targeted test again and record the pass.
+- Run the task verification gate declared below.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `isolated` — 同模块内串行执行，跨模块并行
-- **Review 级别**: `strict` — 新功能需严格审查
-- **隔离键**: 使用模块路径作为隔离键，如 `@isolated(auth/)`
+### Outputs
+- Artifact: src/<module>/
+- Test Artifact: tests/<module>/
+- Execution Notes: docs/plans/<feature-name>/execution-log.md
 
-## 注意事项
+### Verification
+- Targeted: `pnpm test:run tests/<module>`
+- Type safety: `pnpm typecheck`
 
-- 同一模块的 UI 和逻辑建议串行（共享隔离键）
-- 不同模块可并行开发
-- 确保接口契约在实现前确定
-- 新功能必须附带测试任务
+### Done When
+- The user story acceptance criteria are covered by tests or explicit verification.
+- The implementation stays within the declared isolation key unless the plan is revised.
+- The targeted verification gate passes.

package/skills/dev-workflow/references/templates/code-fix-task.md

@@ -1,28 +1,42 @@
-# 代码修复任务模板
+# Code Fix Harness Task Template
 
-```markdown
-## TaskGroup: [Bug 描述]
+## HarnessTask: HT-FIX-1 - Fix Defect
 
-### Meta
-- parallel_limit: 3
+### Control
+- type: code:fix
+- agent_role: implementer
+- scheduler: isolated
+- isolation_key: <file-or-module-path>
+- dependencies: []
 - review_level: standard
-- on_failure: stop
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [research] 定位 [Bug 描述] 根因 @cache(1d)
-2. [code:fix] 修复 [Bug 描述] @isolated([file_path])
-3. [test] 补充回归测试 @isolated([file_path])
-```
+### Inputs
+- Requirement: BUG-<number> or US-<number>
+- Failure Evidence: docs/plans/<feature-name>/requirements.md
+- Context: docs/plans/<feature-name>/execution-log.md
 
-## 使用说明
+### Steps
+- Reproduce or describe the failure from evidence.
+- Add a regression test that fails for the defect.
+- Make the smallest fix inside the isolation key.
+- Rerun the regression test and record the result.
+- Run any broader gate affected by the fix.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `isolated` — 同文件串行
-- **Review 级别**: `standard`
-- **on_failure**: `stop` — 修复失败应立即停止
+### Outputs
+- Artifact: <file-or-module-path>
+- Regression Test: tests/<affected-area>/
+- Execution Notes: docs/plans/<feature-name>/execution-log.md
 
-## 注意事项
+### Verification
+- Regression: `pnpm test:run tests/<affected-area>`
+- Quality: `pnpm lint`
 
-- 先调研再修复，避免盲目改代码
-- 修复和测试使用相同隔离键（同文件）
-- 修复后必须补充回归测试
-- 如涉及多文件，每个文件用独立隔离键
+### Done When
+- The original failure is covered by a regression test or explicit reproduction check.
+- The fix does not change unrelated behavior.
+- The regression gate passes.

package/skills/dev-workflow/references/templates/code-refactor-task.md

@@ -1,30 +1,42 @@
-# 代码重构任务模板
+# Code Refactor Harness Task Template
 
-```markdown
-## TaskGroup: [重构目标]
+## HarnessTask: HT-REF-1 - Refactor Shared Structure
 
-### Meta
-- parallel_limit: 1
+### Control
+- type: code:refactor
+- agent_role: implementer
+- scheduler: serial
+- isolation_key: global
+- dependencies: []
 - review_level: strict
-- on_failure: stop
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [research] 分析当前 [模块] 的问题和依赖关系
-2. [code:refactor] 重构 [模块] 核心结构
-3. [code:fix] 修复重构引入的类型错误
-4. [test] 运行全量测试确认无回归
-```
+### Inputs
+- Requirement: US-<number> or REF-<number>
+- Context: docs/plans/<feature-name>/implementation-plan.md
+- Coverage: docs/plans/<feature-name>/validation-report.md
 
-## 使用说明
+### Steps
+- Identify the public contracts that must remain stable.
+- Add or confirm tests around existing behavior before changing structure.
+- Refactor one bounded area at a time.
+- Run typecheck and targeted tests after each meaningful step.
+- Run full verification gates before review.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `serial` — 强制串行，影响范围大
-- **Review 级别**: `strict` — 重构需严格审查
-- **on_failure**: `stop` — 重构出错应立即停止
+### Outputs
+- Artifact: <refactored-paths>
+- Compatibility Notes: docs/plans/<feature-name>/execution-log.md
 
-## 注意事项
+### Verification
+- Tests: `pnpm test:run`
+- Types: `pnpm typecheck`
+- Build: `pnpm build`
 
-- 重构任务必须串行执行，避免冲突
-- 先分析依赖关系，确定影响范围
-- 重构后必须运行全量测试
-- 大范围重构建议拆分为多个小步骤
-- 每步重构后验证编译通过再继续
+### Done When
+- Public behavior and contracts are preserved or intentionally changed in the plan.
+- Full verification gates pass.
+- Strict review has no blocking findings.

package/skills/dev-workflow/references/templates/doc-write-task.md

@@ -1,29 +1,41 @@
-# 文档编写任务模板
+# Documentation Harness Task Template
 
-```markdown
-## TaskGroup: [文档主题]
+## HarnessTask: HT-DOC-1 - Write Documentation Artifact
 
-### Meta
-- parallel_limit: 5
+### Control
+- type: doc:write
+- agent_role: documenter
+- scheduler: parallel
+- isolation_key: docs/<artifact-name>
+- dependencies: []
 - review_level: light
-- on_failure: continue
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [doc:write] 编写 [模块] API 文档
-2. [doc:write] 编写 [模块] 使用指南
-3. [doc:write] 更新 README
-4. [doc:write] 编写 CHANGELOG
-```
+### Inputs
+- Requirement: US-DOC-<number>
+- Source Context: docs/plans/<feature-name>/requirements.md
+- Plan Context: docs/plans/<feature-name>/implementation-plan.md
 
-## 使用说明
+### Steps
+- Identify the audience and required artifact.
+- Update the target document using the repository's existing style.
+- Keep terminology consistent with related docs.
+- Check links, paths, commands, and examples.
+- Record any assumptions in execution notes.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `parallel` — 完全并行，文档间无冲突
-- **Review 级别**: `light` — 快速检查即可
-- **on_failure**: `continue` — 单篇文档失败不影响其他
+### Outputs
+- Artifact: <documentation-path>
+- Execution Notes: docs/plans/<feature-name>/execution-log.md
 
-## 注意事项
+### Verification
+- Content Review: confirm the document matches source context and contains no stale workflow names.
+- Repository Gate: `pnpm lint`
 
-- 文档任务可完全并行，无需隔离
-- 注意保持文档间的交叉引用一致性
-- 使用项目已有的文档格式和风格
-- 技术文档应包含代码示例
+### Done When
+- The document accurately describes the implemented behavior or workflow.
+- Cross-references point to existing files.
+- Light review has no blocking findings.

package/skills/dev-workflow/references/templates/research-task.md

@@ -1,30 +1,42 @@
-# 调研分析任务模板
+# Research Harness Task Template
 
-```markdown
-## TaskGroup: [调研主题]
+## HarnessTask: HT-RES-1 - Research Decision Input
 
-### Meta
-- parallel_limit: 5
+### Control
+- type: research
+- agent_role: researcher
+- scheduler: parallel
+- isolation_key: research/<topic>
+- dependencies: []
 - review_level: light
-- on_failure: continue
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [research] 调研 [方案A] 的优劣势 @cache(7d)
-2. [research] 调研 [方案B] 的优劣势 @cache(7d)
-3. [research] 对比 [方案A] 和 [方案B] @depends(1,2)
-4. [doc:write] 输出调研结论文档
-```
+### Inputs
+- Requirement: US-<number> or QUESTION-<number>
+- Context Source: MCP source, repository file, official documentation, or user-provided text
+- Decision Needed: <specific decision>
 
-## 使用说明
+### Steps
+- Identify primary sources and repository-local evidence.
+- Gather only the context needed for the decision.
+- Compare viable options with tradeoffs.
+- State the recommendation and why it fits the current codebase.
+- Record citations or file references.
+- If a web or MCP source is blocked by verification, login, or access control, record `source_status` and request a fallback instead of inferring content.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `parallel` — 不同方向可同时调研
-- **Review 级别**: `light`
-- **缓存**: 调研结果可缓存，避免重复工作
+### Outputs
+- Artifact: docs/plans/<feature-name>/research-<topic>.md
+- Decision: recommendation with tradeoffs
 
-## 注意事项
+### Verification
+- Source Check: every factual claim is backed by a cited source or local file reference.
+- Scope Check: recommendation answers the declared decision.
 
-- 使用 `@cache(duration)` 缓存调研结果
-- 多个方案可并行调研
-- 对比分析需等待各方案调研完成（使用 `@depends`）
-- 调研结论应输出为结构化文档
-- 注明信息来源和时效性
+### Done When
+- The decision can be used directly by the harness plan.
+- Unknowns and assumptions are explicit.
+- Light review has no blocking findings.

package/skills/dev-workflow/references/templates/test-task.md

@@ -1,30 +1,41 @@
-# 测试任务模板
+# Test Harness Task Template
 
-```markdown
-## TaskGroup: [测试范围]
+## HarnessTask: HT-TEST-1 - Verify Behavior
 
-### Meta
-- parallel_limit: 5
+### Control
+- type: test
+- agent_role: tester
+- scheduler: parallel
+- isolation_key: tests/<module>/
+- dependencies: []
 - review_level: standard
-- on_failure: continue
+- feedback_mode: quiet_success | actionable_failure
+- retry_limit: 2
 
-### Tasks
-1. [test] 编写 [模块A] 单元测试
-2. [test] 编写 [模块B] 单元测试
-3. [test] 编写 [功能] 集成测试
-4. [test] 运行全量测试并生成覆盖率报告
-```
+### Inputs
+- Requirement: US-<number>
+- Implementation Artifact: <source-path>
+- Acceptance Criteria: docs/plans/<feature-name>/user-stories.md
 
-## 使用说明
+### Steps
+- Identify the behavior, edge case, or regression to verify.
+- Add the smallest test that proves the behavior.
+- Run the test and confirm it fails when the implementation is absent or broken when practical.
+- Restore or keep the implementation and confirm the test passes.
+- Run the broader affected test gate.
+- Keep passing gate output concise; record only the gate name and pass status.
+- On failure, record the command, key error, likely owner, and repair action.
+- Stop after two repair attempts and ask for human direction.
 
-- **并行策略**: `parallel` — 不同模块的测试可并行编写
-- **Review 级别**: `standard`
-- **on_failure**: `continue` — 单模块测试失败不阻塞其他
+### Outputs
+- Artifact: tests/<module>/
+- Execution Notes: docs/plans/<feature-name>/execution-log.md
 
-## 注意事项
+### Verification
+- Targeted: `pnpm test:run tests/<module>`
+- Broader Gate: `pnpm test:run`
 
-- 不同模块的测试可完全并行编写
-- 集成测试可能依赖多个模块，注意声明依赖
-- 全量测试运行应在所有测试编写完成后
-- 关注测试覆盖率目标
-- 使用项目已有的测试框架和模式
+### Done When
+- The test maps to an acceptance criterion or documented regression.
+- The targeted gate passes.
+- Standard review has no blocking findings.