@wnlen/agent-execution-template 0.8.14

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

@@ -0,0 +1,32 @@
+# Result
+
+## Status
+
+blocked
+
+## Summary
+
+No task has been executed yet.
+
+## Changed
+
+- None
+
+## Verified
+
+- Not verified
+
+## Metrics
+
+- Model: not recorded
+- Duration: 0 minutes
+- Success: false
+- Human fix required: false
+
+## Issues
+
+- No current task executed.
+
+## Next
+
+- Read `ai/template/bootstrap.md`, confirm project context, then draft and confirm `ai/project/task.md` before running `ai/template/prompt.md`.

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

@@ -0,0 +1,74 @@
+# Runtime
+
+## Current State
+
+- Phase: Direction-layer and execution-layer consistency pass
+- Focus: Keep the file protocol installable, upgradeable, and auditable while keeping project-direction governance aligned with task execution constraints.
+- Blocker: None
+- Known Risks:
+  - Over-expanding scope beyond the current task
+  - Asking humans for details the agent can infer safely
+  - Polluting runtime context with historical process notes
+  - Marking success without verification evidence
+  - Running commands outside explicit permission
+  - Optimizing for token savings instead of acceptable output per cost
+  - Direction-layer capabilities advancing while rules, runtime, or doctor checks stay on older semantics
+
+## Hard Rules
+
+- Current task first.
+- Do not expand scope.
+- Do not rewrite unrelated files.
+- Do not repeat known background.
+- Do not output tutorials.
+- Do not treat guesses as facts.
+- Read relevant files before making assumptions.
+- Prefer minimal safe changes.
+- Verify after changes when possible.
+- Keep final output short.
+- Minimize human interaction; ask only for scope, risk, permission, or acceptance blockers.
+- Ask at most 3 clarification questions before execution.
+- Do not edit `ai/project/runtime.md` unless explicitly allowed by `ai/project/task.md`.
+- If `status = "success"`, `verification.passed` must be `true`.
+- If verification requires manual checking, use `status = "partial"` unless manual verification has been completed.
+- Default to cheap execution and escalate only for planning, judgment, repeated failure, or acceptance disputes.
+- Follow `ai/project/task.md.model_policy`; default cheap, escalate for judgment, record why.
+
+## Project Constraints
+
+- Bootstrap read set starts from `ai/template/bootstrap.md`, `ai/template/protocol.md`, `ai/template/rules/core.md`, root docs, manifests, docs, refs, and bounded source-structure inspection when docs are insufficient.
+- Execution read set is `ai/template/prompt.md`, `ai/template/protocol.md`, `ai/template/rules/core.md`, `ai/project/project.md`, `ai/project/runtime.md`, and `ai/project/task.md`.
+- `ai/project/refs/` files are loaded only when required by task or triggered by task type.
+- `ai/project/refs/final-shape.md`, `module-map.md`, and `roadmap.md` are official direction-layer documents.
+- Official direction-layer documents must not be modified by routine reconcile flows or routine execution tasks.
+- Direction changes must go through a `strategy_update` proposal and `apply_strategy_update`.
+- `ai/project/archive/` is never read by default.
+- `ai/project/result.json` is the only authoritative latest result.
+- `ai/project/result.md` is the latest human-readable summary.
+- `ai/project/metrics.json` is the latest token-efficiency and reuse record.
+- Model tier decisions are governed by `ai/project/task.md.model_policy`, not by ad hoc chat preference.
+- `ai/project/runtime.md` stores stable, currently valid context only.
+- Historical tasks and results belong in `ai/project/archive/`.
+
+## Active Context
+
+This project is a protocol/template, not a complex agent framework.
+The current product position is: project-direction governance plus auditable task execution for AI Coding Agents.
+The current product goal is to reduce human interaction frequency and input size while making tasks more precise over time and reducing long-term direction drift.
+Small CLI additions that improve protocol adoption and governance closure are allowed; do not introduce UI, cloud sync, or multi-agent orchestration.
+
+## Ref Routing
+
+- 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 / deploy command -> `ai/project/refs/commands.md`
+
+## Runtime Update Governance
+
+AI must not directly update this file unless `ai/project/task.md` explicitly permits it.
+If a task produces long-term valid context, write a proposal to `ai/project/result.json.runtime_update`.
+Apply runtime updates through a separate task whose only allowed target is `ai/project/runtime.md`.

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

@@ -0,0 +1,110 @@
+---
+task_id: ""
+type: "bugfix | feature | refactor | docs | config | test | research | strategy_update | apply_strategy_update"
+priority: "P0 | P1 | P2 | P3"
+risk_level: "low | medium | high"
+depends_on_previous_result: false
+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
+refs:
+  required: []
+  optional: []
+permission:
+  modify:
+    allowed: []
+    denied: []
+  commands:
+    allowed: []
+    denied: []
+  network: false
+  destructive_actions: false
+  runtime_update: "propose_only"
+---
+
+# Task
+
+This file is the current execution contract. Prefer generating it in Bootstrap
+Mode from a short human goal plus repository context, then have a human review
+it before execution.
+
+Prefer safe assumptions over extra questions, but do not guess scope, risk,
+permissions, or acceptance.
+
+## Goal
+
+Describe the exact goal of this task. If generated from a short human request,
+preserve the user's intent and make assumptions explicit.
+
+If `type = strategy_update`, the goal is to produce a direction amendment
+proposal, not code. If `type = apply_strategy_update`, the goal is to merge a
+confirmed proposal into the official direction documents.
+
+## Scope
+
+Allowed scope:
+
+- 
+
+Out of scope:
+
+- 
+
+## Related Files
+
+- 
+
+## Constraints
+
+- Do not refactor unrelated modules.
+- Do not modify public API unless required by the task.
+- Do not edit `ai/project/runtime.md` unless explicitly authorized.
+- Do not modify `ai/project/refs/final-shape.md`, `module-map.md`, or
+  `roadmap.md` unless `type = apply_strategy_update` and a confirmed proposal
+  exists.
+
+## Acceptance
+
+The task is complete when:
+
+- 
+
+## Permission
+
+Modify files only under the allowlist in the YAML front matter.
+Run only commands listed in the YAML front matter and allowed by `ai/project/refs/commands.md`.
+
+## Model Policy
+
+Default to the model tier declared in `model_policy.default_tier`.
+Do not use `strong` for routine execution. Use `strong` only for the roles and
+triggers declared in `model_policy`, then record the reason in `ai/project/metrics.json`.
+
+## Stop Conditions
+
+Stop and write `ai/project/result.json`, `ai/project/result.md`, and `ai/project/metrics.json` with blocked status if:
+
+- Required files are missing.
+- Goal is ambiguous.
+- Acceptance cannot be verified.
+- Scope requires modifying files outside allowed range.
+- Required refs are missing.
+- Required command cannot be run.
+- Risk level is high without explicit authorization.

package/template/en/ai/template/LANG

@@ -0,0 +1 @@
+en

package/template/en/ai/template/VERSION

@@ -0,0 +1 @@
+0.8.14

package/template/en/ai/template/bootstrap.md

@@ -0,0 +1,194 @@
+# AI Execution Bootstrap
+
+Do not summarize this file.
+Execute the bootstrap workflow below.
+
+You are bootstrapping project context for Agent Execution Template.
+
+Goal: build the stable project understanding that future tasks will rely on.
+This is a discovery and confirmation step, not an implementation step.
+
+Your job is to inspect the project, create or update `ai/project/project.md`
+and relevant `ai/project/refs/*`, then stop with the Post-Bootstrap Handoff.
+
+## First Read
+
+1. `ai/template/protocol.md`
+2. `ai/template/rules/core.md`
+3. Existing `ai/project/project.md`
+4. Existing `ai/project/refs/*.md` if present
+
+## Bootstrap Mission
+
+Create or update:
+
+- `ai/project/project.md`
+- `ai/project/refs/final-shape.md` when project direction, final shape, or
+  task-worthiness criteria can be inferred
+- `ai/project/refs/module-map.md` when module responsibilities, boundaries, or
+  dependency direction can be inferred
+- `ai/project/refs/roadmap.md` when stage goals, near-term direction, or
+  deferred items can be inferred
+- `ai/project/refs/architecture.md` when architecture can be inferred
+- `ai/project/refs/commands.md` when run/test/build commands can be inferred
+- `ai/project/refs/constraints.md` when constraints can be inferred
+- `ai/project/refs/decisions.md` only when durable decisions are documented
+
+Create `ai/project/task.md` only if the human also provides a current task.
+If you create `ai/project/task.md`, draft only the task contract. Do not enter execution.
+
+Do not edit source code, tests, app config, dependency files, generated files,
+runtime files, result files, or metrics files during bootstrap.
+
+## Reading Order
+
+Read high-signal project evidence in this order:
+
+1. Root docs: `README*`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING*`, `CHANGELOG*`
+2. Manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
+   `pom.xml`, `build.gradle*`, `Makefile`
+3. Project docs: `docs/**`, preferring overview, architecture, setup, testing,
+   deployment, API, ADR, and decision files
+4. Existing AI refs: `ai/project/refs/*.md`
+5. Shallow repository structure for source, test, config, and docs directories
+
+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 dependency folders, build outputs, coverage outputs, lockfiles
+except to infer package manager, secret files, environment files, or archives
+unless the human explicitly references them.
+
+## Confirmation Dimensions
+
+After reading, summarize and ask the human to confirm or correct these points:
+
+- project name, purpose, and primary users;
+- one-line positioning, final shape, and task-worthiness criteria;
+- current module map, module boundaries, and dependency direction;
+- current stage, near-term roadmap, and what is not being done now;
+- technology stack, package manager, and test runner;
+- source, test, config, and documentation layout;
+- main modules and boundaries;
+- important run, build, test, and verification commands;
+- durable constraints, security boundaries, compatibility requirements, and
+  high-risk areas;
+- unknowns that would affect future task precision.
+
+Ask at most 3 questions at a time. Ask only questions whose answers would
+change project identity, commands, boundaries, constraints, risk, permission,
+or acceptance.
+
+## Output Rules
+
+- Mark unknown facts as `Unknown`; do not present guesses as facts.
+- Initialization content in `final-shape.md`, `module-map.md`, and
+  `roadmap.md` must cite evidence sources. If evidence is insufficient, keep
+  placeholders or write `Unknown`; do not invent a vision.
+- Record evidence sources in the relevant file when useful.
+- Keep `ai/project/project.md` stable and long-lived.
+- Keep `ai/project/refs/*.md` focused; do not turn refs into a project diary.
+- Stop after writing drafts and asking for confirmation.
+- Do not execute implementation work in the same run.
+
+## Post-Bootstrap Handoff
+
+After writing project context drafts, do not only ask the human to open files
+and inspect them. The final response must include a confirmable summary so the
+human can confirm or correct directly in chat.
+
+If the human already provided a current task goal in the bootstrap request, you
+must also draft `ai/project/task.md`, then ask the human to confirm both the
+project understanding and the task draft.
+
+If the human did not provide a current task goal, recommend the next best task
+based on the project state.
+
+The final response must use one of these shapes.
+
+When there is no current task goal:
+
+```text
+Bootstrap is complete. I wrote the project context.
+
+My understanding of the project:
+- Project:
+- Tech stack:
+- Main modules:
+- North Star:
+- Roadmap:
+- Common commands:
+- Important constraints:
+- Still uncertain: up to 3 items; write "none" if there are none
+
+Recommended next step:
+1. Priority task:
+   Reason:
+2. Alternative task:
+   Reason:
+
+Written:
+- 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
+
+Reply with:
+- Confirm, draft task 1
+- Confirm, but do: <one-sentence task>
+- Correction: <what to change>
+```
+
+When there is already a current task goal:
+
+```text
+Bootstrap is complete. I wrote the project context and task draft.
+
+My understanding of the project:
+- Project:
+- Tech stack:
+- Main modules:
+- North Star:
+- Roadmap:
+- Common commands:
+- Important constraints:
+- Still uncertain: up to 3 items; write "none" if there are none
+
+Task draft summary:
+- Goal:
+- Scope:
+- Out of scope:
+- Acceptance:
+- Risk:
+- Permissions needed:
+
+Written:
+- 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
+- ai/project/task.md
+
+Reply with:
+- Confirm, execute
+- Correction: <what to change>
+```
+
+If important unknowns remain, list at most 3 of them under "Still uncertain".
+Do not make the human hunt through files to find issues; file paths are only
+for traceability.

package/template/en/ai/template/prompt.md

@@ -0,0 +1,118 @@
+# AI Execution Prompt
+
+Do not summarize this file.
+Execute the workflow below.
+
+You are operating inside an Agent Execution Template workspace.
+
+First read:
+
+1. `ai/template/protocol.md`
+2. `ai/template/rules/core.md`
+
+Then choose the mode:
+
+- 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` ideas waiting for
+  evaluation, draft a `strategy_update` task or produce the proposal directly,
+  then stop for human confirmation.
+- If the user explicitly confirms that a proposal under
+  `ai/project/proposals/final-shape-updates/*.md` may be merged, draft or
+  execute an `apply_strategy_update` task. If the proposal is still
+  `proposed`, update it to `accepted` based on that explicit confirmation.
+- If the user says "Start initializing this project and absorb the material in ai/project/inbox/",
+  or asks to initialize while also absorbing material from
+  `ai/project/inbox/`, follow `ai/template/bootstrap.md` and treat
+  `ai/project/inbox/*.md` and `ai/project/inbox/raw/*.md` as part of the
+  bootstrap input for this run; stop after project-context confirmation.
+- If the user says "Reconcile the new material in ai/project/inbox/", asks to
+  reconcile, merge, absorb, update context, handle new material, mentions
+  `reconcile` or `ai/project/inbox/`, or if `ai/project/inbox/` contains
+  non-`.gitkeep` material waiting to be absorbed, follow
+  `ai/template/reconcile.md` and stop or update according to its two-phase
+  workflow; `ai/project/inbox/processed/` is already processed material and
+  should not trigger reconciliation, while `ai/project/inbox/ideas/` should
+  route to `strategy_update` first.
+- If the user says "Start initializing this project", asks to initialize,
+  organize, or generate project context, or if `ai/project/project.md` is
+  empty, placeholder-only, or incomplete, follow `ai/template/bootstrap.md`
+  and stop after project-context confirmation.
+- If `ai/project/task.md` is empty, placeholder-only, or incomplete, draft it
+  from the user's current goal and confirmed project context, then stop for
+  human confirmation.
+- If the user says "Continue this project" without a more specific goal, first
+  judge the best next step globally: prioritize pending context confirmation,
+  pending task confirmation, failed results, unfinished tasks, or obvious
+  risks; then recommend a next step or draft `ai/project/task.md`. Do not make
+  the human hunt through files for gaps.
+- Use Execution Mode only after `ai/project/project.md` and
+  `ai/project/task.md` are ready enough to define identity, goal, scope,
+  permission, and acceptance.
+
+## Task Draft Handoff
+
+In Task Draft Mode:
+
+1. Read confirmed `ai/project/project.md` and relevant `ai/project/refs/*.md`.
+2. Draft `ai/project/task.md` from the user's current goal.
+3. Ask at most 3 questions only for scope, risk, permission, or acceptance
+   blockers.
+4. Stop for human confirmation. Do not modify source or business files.
+
+End Task Draft Mode with:
+
+```text
+Task draft is ready.
+
+Please review:
+- ai/project/task.md
+
+Confirm or correct:
+1. Goal and acceptance
+2. Allowed and denied scope
+3. Permissions, commands, and risk level
+
+Reply with:
+- Confirmed, execute
+- Or corrections
+```
+
+## Strategy Update Handoff
+
+In `strategy_update`:
+
+1. Read `final-shape.md`, `module-map.md`, `roadmap.md`, `decisions.md`,
+   `constraints.md`, and relevant `inbox/ideas/*`.
+2. Use `ai/project/proposals/final-shape-updates/_template.md` as the
+   structural template and generate
+   `ai/project/proposals/final-shape-updates/YYYYMMDD-topic.md`.
+3. Stop for human confirmation. Do not modify official direction files or
+   source code.
+
+End with:
+
+```text
+Direction amendment proposal is ready.
+
+Please review:
+- ai/project/proposals/final-shape-updates/YYYYMMDD-topic.md
+
+Reply with:
+- Confirmed, merge this proposal
+- Or corrections
+```
+
+In Execution Mode, read:
+
+1. `ai/project/project.md`
+2. `ai/project/runtime.md`
+3. `ai/project/task.md`
+
+Then execute the task and write results to:
+
+- `ai/project/result.json`
+- `ai/project/result.md`
+- `ai/project/metrics.json`
+
+Keep terminal output short and follow `ai/template/rules/output.md`.