@wnlen/agent-execution-template 0.8.14

package/template/en/ai/template/protocol.md

@@ -0,0 +1,332 @@
+# Protocol
+
+Agent Execution Template v0.8 separates reusable protocol from project-specific
+execution context.
+
+```text
+ai/template/ = reusable execution protocol
+ai/project/  = current project execution workspace
+```
+
+Template is protocol. Project is the field workspace.
+
+The project workspace stores both execution state and direction. The direction
+layer answers "why is this worth doing and where should the project grow"; the
+execution layer answers "what is this task and how will it be accepted."
+
+```text
+ai/project/refs/final-shape.md = project North Star
+ai/project/refs/module-map.md  = current module map
+ai/project/refs/roadmap.md     = staged roadmap
+ai/project/task.md             = current execution contract
+```
+
+## Execution Flow
+
+```text
+Project Bootstrap / Context Reconcile / Strategy Update -> Project Confirm -> Task Draft -> Task Confirm -> Plan -> Execute -> Review -> Result
+```
+
+1. For project discovery, follow `ai/template/bootstrap.md`; do not summarize it.
+2. End bootstrap with the Post-Bootstrap Handoff, including a confirmable
+   in-chat summary and recommended next step. Do not only ask the human to open
+   files and inspect them.
+3. For task execution, follow `ai/template/prompt.md`; do not summarize it.
+4. When new authoritative material appears, put it in `ai/project/inbox/` and
+   follow `ai/template/reconcile.md`; do not summarize it. Reconciliation must
+   produce a plan first and update context only after confirmation.
+5. When a new idea would change the final product shape, module boundaries, or
+   roadmap, put it in `ai/project/inbox/ideas/`, then create a
+   `strategy_update` task to produce a proposal.
+6. Only after the human confirms the proposal may an `apply_strategy_update`
+   task modify `final-shape.md`, `module-map.md`, or `roadmap.md`.
+7. If `ai/project/task.md` is missing or incomplete, draft it from the current
+   goal and confirmed project context, then stop with the Task Draft Handoff.
+8. After task confirmation, check readiness, risk, model policy, refs,
+   permission, and acceptance.
+9. Execute only within the project task boundary.
+10. Write `ai/project/result.json`, `ai/project/result.md`, and `ai/project/metrics.json`.
+
+## Bootstrap Mode
+
+Bootstrap Mode prepares stable project understanding:
+
+- `ai/project/project.md`
+- `ai/project/refs/*.md`
+
+Use Bootstrap Mode when `ai/project/project.md` is empty, placeholder-only,
+stale, incomplete, or the user asks to bootstrap project context.
+
+Bootstrap Mode must:
+
+- read only the approved bootstrap sources first;
+- summarize stable project facts into `ai/project/project.md`;
+- update focused refs when durable architecture, command, constraint, or
+  decision facts can be inferred;
+- create `ai/project/task.md` only if the human also provides a current task,
+  and only draft the task contract;
+- mark unknown facts as `Unknown` instead of guessing;
+- ask at most 3 questions only when answers change scope, risk, permission, or
+  acceptance;
+- stop after writing draft project context files; if a current task was
+  provided, it may also write a task draft before stopping;
+- never edit source, business, config, dependency, or generated files.
+
+### Bootstrap Read Scope
+
+Read high-signal sources in this order:
+
+1. Root documentation:
+   - `README*`
+   - `AGENTS.md`
+   - `CLAUDE.md`
+   - `CONTRIBUTING*`
+   - `CHANGELOG*`
+2. Package and build metadata:
+   - `package.json`
+   - `pyproject.toml`
+   - `Cargo.toml`
+   - `go.mod`
+   - `pom.xml`
+   - `build.gradle*`
+   - `Makefile`
+3. Project documentation:
+   - `docs/**`
+   - prefer overview, architecture, setup, testing, deployment, API, ADR, and
+     decision files.
+4. Existing AI context:
+   - `ai/project/refs/*.md`
+5. Shallow repository structure:
+   - source, test, config, and documentation directories only.
+
+If docs and manifests are missing or insufficient, infer from code with a
+bounded read:
+
+- inspect top-level directories and filenames first;
+- inspect likely entrypoints such as `src/`, `app/`, `lib/`, `packages/`,
+  `services/`, `cmd/`, `internal/`, `server/`, `client/`, `test/`, `tests/`;
+- inspect route, module, config, and test files only enough to identify
+  project purpose, module boundaries, commands, and constraints;
+- do not read the whole codebase unless the human explicitly authorizes it.
+
+Do not read by default:
+
+- dependency directories such as `node_modules`, `vendor`, `.venv`;
+- generated outputs such as `dist`, `build`, `target`, `coverage`;
+- lockfiles except to infer package manager;
+- secret or environment files such as `.env*`;
+- archive/history directories unless the user explicitly references them.
+
+If the repository is large, read the root docs and manifests first, then ask
+before expanding the read scope.
+
+### Bootstrap Outputs
+
+`ai/project/project.md` should contain long-lived project identity:
+
+- name, purpose, and primary users;
+- language, framework, package manager, and test runner;
+- source, test, config, and documentation layout;
+- stable constraints, conventions, and important unknowns.
+
+`ai/project/refs/*.md` should contain focused durable context:
+
+- project North Star, final shape, and task-worthiness criteria;
+- current module map, staged roadmap, and direction constraints;
+- architecture and module boundaries;
+- run, build, test, and verification commands;
+- security, compatibility, performance, data, and deployment constraints;
+- documented decisions only when evidence exists.
+
+Recommended routing:
+
+```text
+final shape / North Star / task worthiness -> ai/project/refs/final-shape.md
+current module structure / boundaries      -> ai/project/refs/module-map.md
+stage goals / near-term roadmap            -> ai/project/refs/roadmap.md
+architecture / API / technical boundaries  -> ai/project/refs/architecture.md
+commands / verification                    -> ai/project/refs/commands.md
+non-negotiable constraints                 -> ai/project/refs/constraints.md
+confirmed key decisions                    -> ai/project/refs/decisions.md
+```
+
+After writing drafts, stop with the Post-Bootstrap Handoff from
+`ai/template/bootstrap.md`. If the human did not provide a current task,
+recommend the next best task. If the human already provided a current task,
+you may also draft `ai/project/task.md`, but do not execute.
+
+## Task Draft Mode
+
+Task Draft Mode prepares the current execution contract:
+
+- `ai/project/task.md`
+
+Use Task Draft Mode when project context is confirmed but `ai/project/task.md`
+is empty, placeholder-only, incomplete, or the human provides a new task goal
+that was not already drafted during bootstrap.
+
+Task Draft Mode should:
+
+- read confirmed `ai/project/project.md`;
+- read relevant `ai/project/refs/*.md`;
+- convert the current human goal into task type, priority, risk, scope,
+  permissions, command policy, model policy, and acceptance criteria;
+- ask at most 3 questions only for scope, risk, permission, or acceptance
+  blockers;
+- stop after writing the task draft with the Task Draft Handoff from
+  `ai/template/prompt.md`;
+- never edit source or business files.
+
+## Context Reconcile Mode
+
+Context Reconcile Mode absorbs new authoritative material and corrects existing
+long-lived context.
+
+New material should usually live in:
+
+- `ai/project/inbox/*.md`
+- `docs/**`
+
+Processed material is moved to `ai/project/inbox/processed/` and is not read
+again as pending intake by default.
+
+The user can simply say "Reconcile the new material in ai/project/inbox/".
+Use Context Reconcile Mode by following `ai/template/reconcile.md`.
+
+Context Reconcile Mode must:
+
+- read existing `ai/project/project.md`, `ai/project/runtime.md`, and `ai/project/refs/*.md`;
+- read the new material named by the human; if none is named, read `ai/project/inbox/*.md`;
+- produce a reconciliation plan first without modifying files;
+- update `ai/project/project.md`, `ai/project/runtime.md`, and `ai/project/refs/*.md` only after human confirmation;
+- after applying reconciliation, move processed `ai/project/inbox/*.md` material to `ai/project/inbox/processed/`;
+- not modify `task.md`, `result.*`, `metrics.json`, source, tests, config, or dependency files by default;
+- not dump raw new material into refs; absorb long-lived, structured, reusable facts.
+
+If new material would change directional content in `final-shape.md`,
+`module-map.md`, or `roadmap.md`, Context Reconcile Mode may only recommend a
+`strategy_update`; it must not directly edit those files.
+
+## Strategy Update Mode
+
+Strategy Update Mode handles changes to project direction, final shape, module
+boundaries, or roadmap.
+
+Use it when:
+
+- `ai/project/inbox/ideas/` contains new product, business, architecture, or
+  direction ideas;
+- the user asks to update the North Star, final shape, product constitution,
+  module map, or roadmap;
+- a routine task discovers that the current execution goal may conflict with
+  project direction.
+
+### `strategy_update`
+
+`strategy_update` only produces a proposal. It does not write code and does not
+modify official direction files.
+
+It must read:
+
+- `ai/project/refs/final-shape.md`
+- `ai/project/refs/module-map.md`
+- `ai/project/refs/roadmap.md`
+- `ai/project/refs/decisions.md`
+- `ai/project/refs/constraints.md`
+- human-specified new material; if none is named, read `ai/project/inbox/ideas/*`
+
+Write the proposal to:
+
+```text
+ai/project/proposals/final-shape-updates/YYYYMMDD-topic.md
+```
+
+Use `ai/project/proposals/final-shape-updates/_template.md` as the structural
+template.
+
+The proposal must include:
+
+1. Summary of the new idea
+2. Alignment with current `final-shape.md`
+3. Conflicts
+4. Parts to absorb
+5. Parts to reject
+6. Impact on the module map
+7. Impact on the roadmap
+8. Suggested diff
+9. Risks
+10. Merge recommendation
+
+Stop after producing the proposal and wait for human confirmation. Do not
+modify `final-shape.md`, `module-map.md`, `roadmap.md`, source, tests, config,
+or dependency files.
+
+### `apply_strategy_update`
+
+`apply_strategy_update` only applies a confirmed proposal.
+
+It requires:
+
+- explicit human confirmation that a proposal may be merged;
+- the proposal is already `accepted`, or is updated from `proposed` to
+  `accepted` immediately before execution based on explicit human confirmation;
+- `task.md.permission.modify.allowed` includes the official direction files
+  that will be changed;
+- applying only the confirmed proposal content, without opportunistic expansion.
+
+Allowed updates:
+
+- `ai/project/refs/final-shape.md`
+- `ai/project/refs/module-map.md`
+- `ai/project/refs/roadmap.md`
+- `ai/project/refs/decisions.md` or `constraints.md` when necessary
+
+After applying:
+
+- update proposal status to `applied`;
+- fill `applied_at`;
+- make `result.md` list the merged proposal, changed files, and items left
+  unmerged.
+
+If the human rejects a proposal, keep the proposal file, update `status` to
+`rejected`, and do not delete that historical strategy record.
+
+## Human-Minimal Task
+
+The human should normally provide intent and confirm generated project and task
+contracts. The agent should draft routine detail from existing docs, manifests,
+refs, and project files.
+
+- Ask at most 3 clarification questions.
+- Ask only when the answer changes scope, risk, permission, or acceptance.
+- Do not ask about details that can be safely inferred from project files.
+- Convert safe uncertainty into explicit assumptions in `ai/project/result.json`.
+- If acceptance remains unverifiable, stop with `status = "blocked"`.
+- If the task is executable, proceed without further human interaction.
+
+## Model Division
+
+Follow `ai/project/task.md.model_policy`.
+
+- Default cheap.
+- Escalate for judgment.
+- Record why.
+
+Use the default tier for routine execution. Use `strong` only when an
+escalation trigger is hit and the required role is listed in
+`strong_model_roles`.
+
+If the host cannot switch models, stop or mark the task `partial`/`blocked`
+with the needed strong-model role.
+
+## Sync Rules
+
+When importing from this template repo into a real project:
+
+- Overwrite only `ai/template/**`.
+- Never overwrite `ai/project/**`.
+
+When flowing improvements from a real project back into this template repo:
+
+- Return only `ai/template/**`.
+- Never return `ai/project/**`.

package/template/en/ai/template/reconcile.md

@@ -0,0 +1,140 @@
+# AI Context Reconcile
+
+Do not summarize this file.
+Execute the context reconciliation workflow below.
+
+You are absorbing new authoritative material into an existing Agent Execution Template project context.
+This is not a fresh bootstrap and not a full overwrite.
+
+Goal: merge long-lived facts from the new material, correct outdated or inaccurate context, and preserve existing context that is still correct.
+
+## When To Use
+
+Use this workflow when a project has been using the template for a while and a more complete or more authoritative business, product, architecture, or process document appears.
+
+New material should usually live in:
+
+- `ai/project/inbox/*.md`
+- `ai/project/inbox/raw/*.md`
+- `docs/**`
+
+`ai/project/inbox/` is the intake area for material that has not yet been
+absorbed. After reconciliation is confirmed, move processed material to
+`ai/project/inbox/processed/` for traceability and to avoid repeated
+reconciliation.
+
+## First Read
+
+1. `ai/template/protocol.md`
+2. `ai/template/rules/core.md`
+3. `ai/project/project.md`
+4. `ai/project/runtime.md`
+5. `ai/project/refs/*.md`
+6. The new material named by the human; if none is named, read `ai/project/inbox/*.md`
+
+Do not read `ai/project/inbox/processed/**`, `ai/project/archive/**`, source,
+tests, config, or dependency files by default unless the human explicitly asks
+you to use them for fact checking.
+
+## Reconciliation Principles
+
+- Do not overwrite the whole context set.
+- Preserve existing context that is still correct.
+- Split new material into the right places:
+  - Project identity, users, and stable conventions -> `ai/project/project.md`
+  - Current valid execution context -> `ai/project/runtime.md`
+  - Final shape / North Star / task-worthiness criteria -> `ai/project/refs/final-shape.md`
+  - Current module structure / boundaries / dependency direction -> `ai/project/refs/module-map.md`
+  - Stage goals / near-term roadmap / deferred items -> `ai/project/refs/roadmap.md`
+  - Architecture / API / module boundaries -> `ai/project/refs/architecture.md`
+  - Commands -> `ai/project/refs/commands.md`
+  - Constraints -> `ai/project/refs/constraints.md`
+  - Durable decisions -> `ai/project/refs/decisions.md`
+- Do not dump raw source text into `refs/*`; absorb structured, long-lived, reusable context.
+- If new material would change directional content in the North Star, module
+  map, or roadmap, only recommend creating a `strategy_update` proposal. Do not
+  directly modify those direction files during context reconciliation.
+- `task.md`, `result.json`, `result.md`, and `metrics.json` usually do not participate in business-context reconciliation unless the human explicitly asks you to extract long-lived facts from them.
+
+## Two-Phase Workflow
+
+### Phase 1: Reconciliation Plan
+
+First produce a reconciliation plan. Do not modify files.
+
+The plan must include:
+
+1. Content to add
+2. Content to correct
+3. Conflicts with existing context
+4. Content to remove or downgrade
+5. Questions requiring human confirmation, at most 3
+6. Files expected to change
+
+If there are no questions requiring confirmation, explicitly write "no extra confirmation needed".
+
+Stop at the end of Phase 1 and wait for human confirmation.
+
+### Phase 2: Apply Reconciliation
+
+Only update files after the human explicitly confirms the reconciliation plan.
+
+Allowed targets:
+
+- `ai/project/project.md`
+- `ai/project/runtime.md`
+- `ai/project/refs/*.md`
+- `ai/project/inbox/processed/**`, for material processed in this run
+
+Do not modify these unless the human explicitly asks:
+
+- Source, tests, config, dependency files
+- `ai/project/refs/final-shape.md`
+- `ai/project/refs/module-map.md`
+- `ai/project/refs/roadmap.md`
+- `ai/project/task.md`
+- `ai/project/result.json`
+- `ai/project/result.md`
+- `ai/project/metrics.json`
+- `ai/project/archive/**`
+
+After applying reconciliation, move the processed `ai/project/inbox/*.md`
+material into `ai/project/inbox/processed/`. If a filename conflicts, keep the
+original name and add a date or sequence number. Do not move
+`ai/project/inbox/ideas/**`; direction ideas should continue through
+`strategy_update`.
+
+## Final Handoff
+
+After applying reconciliation, the final response must include:
+
+```text
+Context reconciliation is complete.
+
+Updated:
+- file
+
+Archived material:
+- ai/project/inbox/processed/file.md
+
+Key changes:
+- Added:
+- Corrected:
+- Deprecated:
+
+Still uncertain:
+- Up to 3 items; write "none" if there are none
+
+Recommended next step:
+1. Priority task:
+   Reason:
+2. Alternative task:
+   Reason:
+
+Reply with:
+- Confirm, draft task 1
+- Confirm, but do: <one-sentence task>
+- Correction: <what to change>
+```
+
+Do not make the human hunt through files to find changes; file paths are only for traceability.

package/template/en/ai/template/rules/core.md

@@ -0,0 +1,197 @@
+# Core Rules
+
+## Readiness Gate
+
+Before editing code, check that `ai/project/task.md` clearly defines:
+
+- Goal
+- Scope
+- Acceptance
+- Permission
+
+If readiness fails, do not edit code. Write blocked results to:
+
+- `ai/project/result.json`
+- `ai/project/result.md`
+- `ai/project/metrics.json`
+
+## Bootstrap Gate
+
+If `ai/project/project.md` is empty, placeholder-only, incomplete, or the user
+asks to bootstrap project context, follow `ai/template/bootstrap.md` before
+execution.
+
+Bootstrap Mode may write only project context files:
+
+- `ai/project/project.md`
+- `ai/project/refs/final-shape.md`
+- `ai/project/refs/module-map.md`
+- `ai/project/refs/roadmap.md`
+- `ai/project/refs/architecture.md`
+- `ai/project/refs/commands.md`
+- `ai/project/refs/constraints.md`
+- `ai/project/refs/decisions.md`
+
+Bootstrap Mode may write `ai/project/task.md` only if the human also provides
+a current task goal. In that case, draft only the task contract and do not
+enter implementation.
+
+Bootstrap Mode must not edit source code, tests, configuration, dependency
+files, generated files, runtime files, result files, or metrics files.
+
+After writing bootstrap drafts, stop with the Post-Bootstrap Handoff from
+`ai/template/bootstrap.md`. The handoff must include a confirmable in-chat
+summary and recommended next step, not only file paths to inspect. If the human
+already provided a current task goal, bootstrap may also draft
+`ai/project/task.md` in the same run, but it must still stop for confirmation
+and must not enter implementation.
+
+## Bootstrap Read Scope
+
+Read only high-signal project sources by default:
+
+- Root docs: `README*`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING*`, `CHANGELOG*`
+- Manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
+  `pom.xml`, `build.gradle*`, `Makefile`
+- Project docs: `docs/**`, preferring overview, architecture, setup, testing,
+  deployment, API, ADR, and decision files
+- Existing AI refs: `ai/project/refs/*.md`
+- Shallow source/test/config/docs directory listing
+- If docs are missing or insufficient, bounded reads of likely entrypoints such
+  as `src/`, `app/`, `lib/`, `packages/`, `services/`, `cmd/`, `internal/`,
+  `server/`, `client/`, `test/`, and `tests/`
+
+Do not read dependency folders, build outputs, coverage outputs, secret files,
+environment files, or archives unless explicitly authorized or referenced by
+the user.
+
+## Task Draft Gate
+
+If project context is confirmed but `ai/project/task.md` is empty,
+placeholder-only, incomplete, or the human provides a new task goal, draft
+`ai/project/task.md` from confirmed project context and stop for human
+confirmation before implementation.
+
+Task Draft Mode may write only:
+
+- `ai/project/task.md`
+
+Task Draft Mode must end with the Task Draft Handoff from
+`ai/template/prompt.md`.
+
+## Context Reconcile Gate
+
+If the user provides new authoritative business, product, architecture, or
+process material and wants it merged into existing context, or says
+"Reconcile the new material in ai/project/inbox/", follow
+`ai/template/reconcile.md`. Do not re-bootstrap and do not overwrite the whole
+context set.
+
+New material should usually live in:
+
+- `ai/project/inbox/*.md`
+- `ai/project/inbox/raw/*.md`
+- `docs/**`
+
+Processed material is moved to `ai/project/inbox/processed/` and should not
+trigger context reconciliation again by default.
+
+Context reconciliation must produce a plan first and wait for human
+confirmation before updating files.
+
+By default, context reconciliation may update only:
+
+- `ai/project/project.md`
+- `ai/project/runtime.md`
+- `ai/project/refs/*.md`
+
+If new material would change directional content in the North Star, module map,
+or roadmap, Context Reconcile Mode may only recommend a `strategy_update`. It
+must not directly modify:
+
+- `ai/project/refs/final-shape.md`
+- `ai/project/refs/module-map.md`
+- `ai/project/refs/roadmap.md`
+
+Do not modify current task, results, metrics, archives, source, tests, config,
+or dependency files unless the human explicitly authorizes it.
+
+## Strategy Update Gate
+
+If the user asks to update the North Star, final shape, product constitution,
+module map, roadmap, or project direction, or if
+`ai/project/inbox/ideas/` contains non-`.gitkeep` new ideas, execute
+`strategy_update`.
+
+`strategy_update` may only:
+
+- read official direction docs, decisions, constraints, and idea inputs;
+- use `ai/project/proposals/final-shape-updates/_template.md` as its structural
+  template;
+- create `ai/project/proposals/final-shape-updates/YYYYMMDD-topic.md`;
+- set the new proposal status to `proposed`;
+- stop for human confirmation.
+
+It must not directly modify official direction docs, source, tests, config, or
+dependency files.
+
+Only after the human explicitly confirms a proposal may
+`apply_strategy_update` run. During application:
+
+- the confirmed proposal should move from `proposed` to `accepted`, or already
+  be `accepted`;
+- after merge, update the proposal to `applied` and fill `applied_at`;
+- if the human rejects the proposal, keep the file and set `status` to
+  `rejected`;
+- apply only confirmed content, without opportunistic expansion.
+
+## Risk Gate
+
+Before editing code or running commands, check whether the task involves:
+
+- Data migration
+- Authentication / authorization
+- Payment / SMS / external callbacks
+- Public API changes
+- Production deployment
+- Broad refactoring
+- Irreversible or destructive actions
+
+If risk is high and not explicitly authorized in `ai/project/task.md`, stop and
+write blocked results.
+
+## Ref Loading
+
+Read refs only when needed or required by `ai/project/task.md`:
+
+- Final shape / North Star / task-worthiness -> `ai/project/refs/final-shape.md`
+- Current module structure / boundaries / dependency direction -> `ai/project/refs/module-map.md`
+- Stage goals / near-term roadmap / deferred work -> `ai/project/refs/roadmap.md`
+- Architecture / API / module boundary -> `ai/project/refs/architecture.md`
+- Historical decision -> `ai/project/refs/decisions.md`
+- Security / compatibility / performance / data / deployment -> `ai/project/refs/constraints.md`
+- Build / test / run / deploy command -> `ai/project/refs/commands.md`
+
+Record every ref read in `ai/project/result.json.refs_read` with a reason.
+
+## Execution Rules
+
+- Current task first.
+- Do not expand scope.
+- Do not scan unrelated files.
+- Do not rewrite unrelated modules.
+- Read files before guessing.
+- Modify only files allowed by `ai/project/task.md`.
+- Run only commands allowed by `ai/project/task.md` and `ai/project/refs/commands.md`.
+- Prefer minimal safe changes.
+- Record assumptions in `ai/project/result.json`.
+- Verify when possible.
+- Do not mark `status = "success"` unless verification passed.
+- Do not edit `ai/project/runtime.md` unless `ai/project/task.md` explicitly allows it.
+- If runtime changes are needed, propose them in `ai/project/result.json.runtime_update`.
+
+## Runtime Governance
+
+`ai/project/runtime.md` stores stable, currently valid execution context only.
+It is not a project diary. Historical tasks and results belong in
+`ai/project/archive/`.