@wnlen/agent-execution-template 0.8.14

package/docs/token-efficient-protocol-v0.1.md

@@ -0,0 +1,101 @@
+# Token 高效 AI 执行协议 v0.1
+
+这个 profile 建立在 Agent Execution Template 文件协议 v0.8 之上。
+目标不是孤立地最小化 token 使用量，而是在减少人类交互频率和输入量的同时，
+用单位模型成本产出更多可接受的工作。
+
+## 核心原则
+
+默认使用低成本执行。只在关键判断点升级。
+
+## 模型角色
+
+- 强模型：规划、需求判断、架构复核、失败复盘、验收争议。
+- 低成本模型：有边界的读取、小改动、草稿、重复检查、机械清理。
+
+## 模型分工协议
+
+模型分工在每个任务的 `ai/project/task.md.model_policy` 中声明。
+
+```yaml
+model_policy:
+  default_tier: "cheap"
+  allowed_tiers:
+    - cheap
+    - standard
+    - strong
+  escalation_allowed: true
+  escalation_triggers:
+    - ambiguous_goal
+    - ambiguous_acceptance
+    - high_risk_change
+    - architecture_boundary
+    - repeated_failure
+    - verification_dispute
+  strong_model_roles:
+    - planning
+    - risk_judgment
+    - architecture_review
+    - failure_review
+    - acceptance_judgment
+```
+
+协议定义的是档位，不是某个供应商的具体模型名。
+
+- `cheap`：文件读取、上下文清理、任务起草、小改动、检查、结果写入。
+- `standard`：中等实现工作或跨模块编辑。
+- `strong`：规划、风险判断、架构复核、失败复盘、验收判断。
+
+如果需要升级但宿主无法切换模型，Agent 应停止，或将任务标记为
+`partial` / `blocked`，并记录所需的强模型角色。
+
+模型策略执行情况记录在 `ai/project/metrics.json`。
+
+## 执行形态
+
+```text
+项目引导 -> 项目确认 -> 任务草稿 -> 任务确认 -> 计划 -> 执行 -> 复核 -> 结果
+```
+
+在基础循环被真实项目证明可靠之前，不要增加动态 DAG、多 Agent 通信或模型矩阵。
+
+## 必需记录
+
+- `ai/template/`：可复用执行协议。
+- `ai/project/task.md`：目标、范围、权限、风险和验收标准。
+- `ai/project/runtime.md`：每次运行都会读取的紧凑稳定上下文。
+- `ai/project/result.json`：机器可读事实、验证、假设和下一步。
+- `ai/project/result.md`：人类可读摘要。
+- `ai/project/metrics.json`：模型档位、token 估算、耗时、成功状态、人工修复和复用潜力。
+
+## 升级触发条件
+
+在以下情况升级到更强模型：
+
+- 目标或验收标准含糊。
+- 任务触及高风险区域。
+- 需要架构或公共契约判断。
+- 执行器反复失败。
+- 验证结果存在争议，或无法自信解释。
+
+在 `ai/project/metrics.json` 中记录升级。
+
+## 最少人类输入规则
+
+人类通常只需要确认生成的项目上下文和任务契约。
+Agent 应从现有文档、清单、有限代码读取、项目上下文、历史结果和引用中起草
+`ai/project/project.md`、refs 和 `ai/project/task.md`。
+
+- 最多问 3 个澄清问题。
+- 只在答案会改变范围、风险、权限或验收时提问。
+- 优先使用显式假设，而不是低价值来回确认。
+- 将重复假设转成 `ai/project/runtime.md` 更新建议。
+- 将重复成功模式转成未来任务模板或技能。
+
+## 五条操作规则
+
+1. 强模型是顾问，不是默认执行器。
+2. 低成本模型处理边界清楚、验收明确的小任务。
+3. 任务应足够原子，能够独立执行、验证和重跑。
+4. 每次运行都必须留下可审计的任务、输入、输出、失败、成本和验证记录。
+5. 每次运行都应为未来的技能、规则、模板或评估创造原材料。

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@wnlen/agent-execution-template",
+  "version": "0.8.14",
+  "description": "Low-friction AI execution protocol template for coding agents.",
+  "bin": {
+    "agent-execution-template": "bin/agent-execution-template.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "template",
+    "test",
+    "README.md"
+  ],
+  "scripts": {
+    "doctor": "node bin/agent-execution-template.js doctor",
+    "test": "node test/selftest.js"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "codex",
+    "claude-code",
+    "template"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wnlen/agent-execution-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wnlen/agent-execution-template/issues"
+  },
+  "homepage": "https://github.com/wnlen/agent-execution-template#readme",
+  "license": "MIT"
+}

package/template/en/ai/README.md

@@ -0,0 +1,130 @@
+# ai/ Execution Layer
+
+Copy this folder into a target software project.
+
+```text
+template is protocol
+project is the field workspace
+```
+
+## Files
+
+- `template/prompt.md`: AI startup prompt.
+- `template/bootstrap.md`: project discovery and context bootstrap prompt.
+- `template/reconcile.md`: merge new authoritative material into existing project context.
+- `template/VERSION`: installed template version.
+- `template/protocol.md`: bootstrap flow, execution flow, model division, sync rules.
+- `template/rules/core.md`: bootstrap scope, readiness, risk, refs, permissions, runtime governance.
+- `template/rules/output.md`: result and metrics output rules.
+- `template/schemas/`: optional result and metrics validation.
+- `project/project.md`: stable project identity.
+- `project/runtime.md`: current execution context.
+- `project/task.md`: current task contract.
+- `project/result.json`: latest authoritative execution result.
+- `project/result.md`: latest human-readable execution summary.
+- `project/metrics.json`: latest model, token, time, success, and reuse signals.
+- `project/refs/final-shape.md`: project North Star / final shape.
+- `project/refs/module-map.md`: current module map.
+- `project/refs/roadmap.md`: staged roadmap.
+- `project/refs/`: detailed references loaded only when needed.
+- `project/inbox/ideas/`: product, business, architecture, or direction ideas waiting for evaluation.
+- `project/inbox/processed/`: new material already absorbed into context, kept for traceability.
+- `project/inbox/raw/`: raw long-form inputs, interviews, notes, or fragments.
+- `project/inbox/`: new material waiting to be absorbed, such as authoritative business docs.
+- `project/proposals/final-shape-updates/`: North Star and roadmap amendment proposals.
+- `project/proposals/final-shape-updates/_template.md`: direction amendment proposal template.
+- `project/archive/`: historical tasks/results, not read by default.
+
+## Normal Use
+
+When first connecting a project, tell the AI tool:
+
+```text
+Start initializing this project
+```
+
+Common entries later:
+
+- Continue work: `Continue this project`
+- Absorb new material: put it in `project/inbox/`, then say `Reconcile the new material in ai/project/inbox/`
+- Resummarize and improve project context: run `npx -y @wnlen/agent-execution-template refresh`
+- Evaluate a new direction or idea: put it in `project/inbox/ideas/`, then say `Generate a direction amendment proposal from ai/project/inbox/ideas/`
+- Recover the next step: run `npx -y @wnlen/agent-execution-template next`
+
+Rule of thumb:
+
+- Material = confirmed facts, docs, workflows, APIs, or business rules.
+- Direction = undecided ideas, product strategy, architecture changes, or roadmap changes.
+
+Review `project/result.json`, `project/result.md`, and `project/metrics.json` after execution.
+Archive old task/result files if needed.
+
+## Context Reconcile
+
+When more complete or more authoritative material appears, put it in:
+
+```text
+ai/project/inbox/
+```
+
+Then ask the AI tool:
+
+```text
+Reconcile the new material in ai/project/inbox/
+```
+
+The workflow produces a reconciliation plan first and updates `project.md`,
+`runtime.md`, and `refs/*` only after confirmation. After reconciliation,
+processed material is moved to `ai/project/inbox/processed/`.
+
+## Direction Amendments
+
+The North Star, module map, and roadmap belong to the project direction layer:
+
+```text
+ai/project/refs/final-shape.md
+ai/project/refs/module-map.md
+ai/project/refs/roadmap.md
+```
+
+Routine execution tasks must not edit these files directly. Put new ideas in:
+
+```text
+ai/project/inbox/ideas/
+```
+
+Then have the AI produce a `strategy_update` proposal. After human
+confirmation, use `apply_strategy_update` to merge it into the official
+direction documents.
+
+## Sync Rules
+
+From the template repo into a real project:
+
+- Overwrite only `ai/template/**`.
+- Never overwrite `ai/project/**`.
+
+From a real project back into the template repo:
+
+- Return only `ai/template/**`.
+- Never return `ai/project/**`.
+
+## Bootstrap Rule
+
+- The human provides intent, hard constraints, and final acceptance.
+- The agent drafts `project/project.md` and relevant `project/refs/*` from existing docs, manifests, refs, and project files.
+- The agent drafts `project/task.md` after the human provides the current task goal.
+- The human reviews and confirms project and task drafts before execution.
+- Bootstrap may write only project context files, plus `project/task.md` when a current task is provided.
+- Bootstrap must not edit source code, tests, configuration, dependency files, generated files, runtime files, result files, or metrics files.
+- Ask at most 3 clarification questions.
+- Ask only when the answer changes scope, risk, permission, or acceptance.
+- Repeated assumptions should become `project/runtime.md` update proposals.
+
+## Model Division Protocol
+
+- Model policy lives in `project/task.md.model_policy`.
+- Use `cheap` by default for routine execution.
+- Use `standard` for moderate implementation complexity.
+- Use `strong` only for planning, risk judgment, architecture review, failure review, or acceptance judgment.
+- Record actual tier, trigger, role, and escalation reason in `project/metrics.json`.

package/template/en/ai/project/inbox/.gitkeep

@@ -0,0 +1 @@
+

package/template/en/ai/project/inbox/ideas/.gitkeep

@@ -0,0 +1 @@
+

package/template/en/ai/project/inbox/raw/.gitkeep

@@ -0,0 +1 @@
+

package/template/en/ai/project/metrics.json

@@ -0,0 +1,20 @@
+{
+  "protocol_version": "0.8",
+  "task_id": "",
+  "task_type": "",
+  "model": "",
+  "model_tier": "cheap",
+  "escalated": false,
+  "escalation_reason": "",
+  "model_policy_followed": true,
+  "escalation_trigger_hit": "",
+  "strong_model_role": "",
+  "input_tokens_estimated": 0,
+  "output_tokens_estimated": 0,
+  "duration_minutes": 0,
+  "success": false,
+  "human_fix_required": false,
+  "failure_reason": "",
+  "reuse_potential": "low",
+  "notes": []
+}

package/template/en/ai/project/project.md

@@ -0,0 +1,42 @@
+# Project
+
+This file is the stable project identity used by Agent Execution Template.
+Prefer generating it in Bootstrap Mode from existing repository docs and
+manifests, then have a human review it. Mark unknown facts as `Unknown`.
+
+## Identity
+
+- Name:
+- Purpose:
+- Primary users:
+
+## Technology
+
+- Language:
+- Framework:
+- Package manager:
+- Test runner:
+
+## Structure
+
+- Source:
+- Tests:
+- Configuration:
+- Documentation:
+- Direction docs: `ai/project/refs/final-shape.md`, `module-map.md`, `roadmap.md`
+
+## Stable Constraints
+
+- 
+
+## Unknowns
+
+- 
+
+## Notes
+
+Keep this file for stable project identity and long-lived conventions.
+Use `ai/project/refs/final-shape.md` for project direction and final shape.
+Use `ai/project/refs/module-map.md` for current module structure.
+Use `ai/project/refs/roadmap.md` for staged direction.
+Use `ai/project/runtime.md` for current execution context.

package/template/en/ai/project/proposals/final-shape-updates/.gitkeep

@@ -0,0 +1 @@
+

package/template/en/ai/project/proposals/final-shape-updates/_template.md

@@ -0,0 +1,64 @@
+---
+proposal_id: ""
+status: "proposed"
+created_at: ""
+confirmed_by: ""
+applied_at: ""
+source_ideas: []
+target_files:
+  - ai/project/refs/final-shape.md
+  - ai/project/refs/module-map.md
+  - ai/project/refs/roadmap.md
+---
+
+# Direction Amendment Proposal
+
+Status rules:
+
+- `proposed`: generated by the agent and waiting for human review.
+- `accepted`: explicitly confirmed by the human and ready for apply.
+- `rejected`: explicitly rejected by the human and retained for traceability.
+- `applied`: merged by `apply_strategy_update`, with `applied_at` filled.
+
+## 1. Summary of the New Idea
+
+-
+
+## 2. Alignment With Current final-shape
+
+-
+
+## 3. Conflicts
+
+-
+
+## 4. Parts to Absorb
+
+-
+
+## 5. Parts to Reject
+
+-
+
+## 6. Impact on the Module Map
+
+-
+
+## 7. Impact on the Roadmap
+
+-
+
+## 8. Suggested Diff
+
+```diff
+
+```
+
+## 9. Risks
+
+-
+
+## 10. Merge Recommendation
+
+- Recommendation:
+- Reason:

package/template/en/ai/project/refs/architecture.md

@@ -0,0 +1,23 @@
+# Architecture
+
+## System Overview
+
+Describe the target project's system shape only when needed.
+
+## Main Modules
+
+- Module:
+  - Responsibility:
+  - Boundaries:
+
+## Data Flow
+
+Describe important data flow.
+
+## API Flow
+
+Describe important API flow.
+
+## Deployment Shape
+
+Describe deployment shape only if it affects coding tasks.

package/template/en/ai/project/refs/commands.md

@@ -0,0 +1,43 @@
+# Commands
+
+Commands are permissioned by category.
+AI may run only commands allowed by `ai/project/task.md` and this file.
+
+## Safe Verify Commands
+
+```bash
+# Add project-specific safe commands here
+# examples:
+# npm run lint
+# npm run build
+# mvn test
+```
+
+## Local Run Commands
+
+```bash
+# Add local startup commands here
+# examples:
+# npm run dev
+# mvn spring-boot:run
+```
+
+## Dangerous Commands
+
+These require explicit task-level authorization:
+
+```bash
+# database migration
+# deployment
+# branch reset
+# file deletion
+```
+
+## Forbidden Unless Explicitly Allowed
+
+```bash
+# production deploy
+# production data migration
+# destructive cleanup
+# commands that expose secrets
+```

package/template/en/ai/project/refs/constraints.md

@@ -0,0 +1,24 @@
+# Constraints
+
+## Data
+
+- Preserve data consistency.
+- Do not introduce migrations unless explicitly authorized.
+
+## Security
+
+- Do not weaken authentication, authorization, validation, or secrets handling.
+- Do not log sensitive data.
+
+## Compatibility
+
+- Preserve public API compatibility unless explicitly authorized.
+
+## Performance
+
+- Avoid broad refactors without benchmark or clear acceptance criteria.
+
+## Deployment / Rollback
+
+- Do not deploy unless explicitly authorized.
+- Prefer reversible changes.

package/template/en/ai/project/refs/decisions.md

@@ -0,0 +1,13 @@
+# Decisions
+
+Record durable technical decisions here.
+
+## D001 - Example Decision
+
+Status: accepted | superseded | rejected
+
+Reason:
+
+Impact:
+
+Do not change unless:

package/template/en/ai/project/refs/final-shape.md

@@ -0,0 +1,59 @@
+# Project North Star
+
+This file is the project's constitution layer, also called the Product
+Constitution / Final Shape Spec. It stores the project's intended final shape
+and judgment criteria. It should be stable, but it can be revised through an
+explicit process.
+
+Routine execution tasks must not edit this file directly. New ideas should go
+to `ai/project/inbox/ideas/`, then a `strategy_update` task should produce a
+proposal. Only after human confirmation should an `apply_strategy_update` task
+merge it.
+
+## One-Line Positioning
+
+-
+
+## Essential Problem
+
+-
+
+## Target Users
+
+-
+
+## Core Pain Points
+
+-
+
+## Final Product Shape
+
+-
+
+## Not Now
+
+-
+
+## Core Module Boundaries
+
+-
+
+## Long-Term Moat
+
+-
+
+## Task Worthiness Criteria
+
+-
+
+## Drift Criteria
+
+-
+
+## Amendment Rules
+
+- Ideas must not directly modify this file.
+- Agents must not casually edit this file during routine execution.
+- Changes must go through `proposal -> review -> human confirm -> update`.
+- Confirmed changes should also evaluate `module-map.md`, `roadmap.md`,
+  `decisions.md`, and `constraints.md`.

package/template/en/ai/project/refs/module-map.md

@@ -0,0 +1,31 @@
+# Module Map
+
+This file describes the current module structure, boundaries, and dependency
+direction. It answers "what shape does the system currently have" and does not
+replace the directional judgment in `final-shape.md`.
+
+## Module Overview
+
+| Module | Responsibility | Input | Output | Owner/Boundary |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## Dependency Direction
+
+-
+
+## Stable Boundaries
+
+-
+
+## Ambiguous Boundaries
+
+-
+
+## Areas to Split or Merge
+
+-
+
+## Relationship to North Star
+
+-

package/template/en/ai/project/refs/roadmap.md

@@ -0,0 +1,31 @@
+# Roadmap
+
+This file describes staged direction. It answers "where should the project grow
+next" and does not replace `task.md` as the current work order.
+
+## Current Stage
+
+- Stage name:
+- Stage goal:
+- Success signal:
+
+## Near-Term Roadmap
+
+| Stage | Goal | Key Deliverables | Not Doing | Exit Criteria |
+| --- | --- | --- | --- | --- |
+|  |  |  |  |  |
+
+## Completed Stages
+
+-
+
+## Deferred
+
+-
+
+## Roadmap Amendment Rules
+
+- Routine execution tasks may propose roadmap updates, but must not directly
+  edit this file.
+- Changes involving project direction, module boundaries, or stage goals must
+  go through a `strategy_update` proposal.

package/template/en/ai/project/result.json

@@ -0,0 +1,34 @@
+{
+  "protocol_version": "0.8",
+  "status": "blocked",
+  "task_id": "",
+  "task_summary": "No task has been executed yet.",
+  "scope_followed": true,
+  "files_read": [],
+  "refs_read": [],
+  "files_changed": [],
+  "commands_run": [],
+  "verification": {
+    "level": "none",
+    "passed": false,
+    "evidence": []
+  },
+  "evidence": {
+    "git_diff_summary": "",
+    "changed_files_from_git": [],
+    "command_outputs": [],
+    "unverified_claims": []
+  },
+  "assumptions": [],
+  "issues": [
+    "No current task executed."
+  ],
+  "next": [
+    "Ask the agent to read ai/template/bootstrap.md, confirm project context, then draft and confirm ai/project/task.md before running ai/template/prompt.md."
+  ],
+  "runtime_update": {
+    "required": false,
+    "changes": [],
+    "reason": ""
+  }
+}