@damphuquy/agent-init 1.0.2 → 1.0.3

package/templates/process/_seeds/decision-template.md.seed

@@ -0,0 +1,143 @@
+# Decision: [DEC-ID] [Task ID]
+
+<technical_decision task_id="[TASK-ID]" dec_id="[DEC-ID]" version="1.0" framework="RIPER-5">
+
+<!-- READ-ONLY PHASE. Present options. Do not decide without engineer approval. -->
+<decision_status>
+  <phase>INNOVATE</phase>
+  <mode>READ-ONLY</mode>
+  <decision_owner></decision_owner>
+  <last_updated></last_updated>
+</decision_status>
+
+---
+
+## 1. Context
+
+<context>
+  <task>[Link to task.md or task ID]</task>
+  <research_artifact>[Link to research.md]</research_artifact>
+  <constraints>
+    [Key constraints from research that narrow the solution space.]
+  </constraints>
+</context>
+
+---
+
+## 2. Decision Required
+
+<decision_question>
+  [Precise statement of what must be decided. One question per decision artifact.]
+</decision_question>
+
+---
+
+## 3. Options
+
+<options>
+
+  <option id="A">
+    <approach>[High-level implementation approach]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Backward compatibility impact]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, lock contention, rollback complexity]</concurrency_transaction_risk>
+    <testability>[How easy to verify this option]</testability>
+    <maintainability>[Long-term maintenance burden]</maintainability>
+  </option>
+
+  <option id="B">
+    <approach>[High-level implementation approach]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Backward compatibility impact]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, lock contention, rollback complexity]</concurrency_transaction_risk>
+    <testability>[How easy to verify this option]</testability>
+    <maintainability>[Long-term maintenance burden]</maintainability>
+  </option>
+
+  <option id="C">
+    <approach>[High-level implementation approach]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Backward compatibility impact]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, lock contention, rollback complexity]</concurrency_transaction_risk>
+    <testability>[How easy to verify this option]</testability>
+    <maintainability>[Long-term maintenance burden]</maintainability>
+  </option>
+
+</options>
+
+---
+
+## 4. Trade-off Matrix
+
+<tradeoff_matrix>
+
+| Criterion | A | B | C |
+|---|:---:|:---:|:---:|
+| Compatibility | | | |
+| Complexity | | | |
+| Risk | | | |
+| Testability | | | |
+| Maintainability | | | |
+
+<!-- Score: 1 (poor) → 5 (excellent) -->
+</tradeoff_matrix>
+
+---
+
+## 5. Recommendation
+
+<recommendation>
+  [Agent's recommended option with rationale. This is a proposal — engineer decides.]
+</recommendation>
+
+---
+
+## 6. Engineer Decision
+
+<!-- This section must be completed by the engineer before Gate 1 passes -->
+<engineer_decision>
+  <selected_option></selected_option>
+  <rationale></rationale>
+  <rejected_alternatives>
+    - Option [X]: [Reason rejected]
+  </rejected_alternatives>
+</engineer_decision>
+
+---
+
+## 7. Constraints Created by This Decision
+
+<constraints_created>
+  [List any new constraints on implementation that flow into plan.md]
+  -
+</constraints_created>
+
+---
+
+## 8. Evidence Still Required
+
+<evidence_required>
+  [Any facts not yet confirmed that must be verified during the Plan or Execute phase]
+  -
+</evidence_required>
+
+---
+
+## Gate 1 — Decision Approved
+
+<gate id="G1">
+  - [ ] All options presented and trade-offs analyzed.
+  - [ ] Engineer reviewed options.
+  - [ ] Engineer selected option recorded above.
+  - [ ] No blocking business / schema / security decision remains open.
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</technical_decision>

package/templates/process/_seeds/handoff-template.md.seed

@@ -0,0 +1,79 @@
+# Handoff: [TASK-ID]
+
+<handoff task_id="[TASK-ID]" version="2.0" framework="RIPER-5">
+
+<!-- Final projection. Short. Do not duplicate research/plan/review artifacts. -->
+<!-- Answer: What changed? Why? What proves it? What remains risky? -->
+
+<handoff_status>
+  <review_decision>PASS</review_decision>  <!-- Must be PASS before handoff is valid -->
+  <review_artifact>[Link to review.md]</review_artifact>
+  <completed_date></completed_date>
+</handoff_status>
+
+---
+
+## 1. What Changed
+
+<what_changed>
+  [Concise summary of the behavior change delivered. Reference the task goal.]
+</what_changed>
+
+<main_changes>
+  - `path/to/file` — [Nature of change]
+</main_changes>
+
+---
+
+## 2. Why
+
+<why>
+  [Business/technical rationale. One paragraph. Link to task.md for full context.]
+</why>
+
+---
+
+## 3. What Proves It
+
+<evidence>
+
+| AC | Verifier | Result |
+|---|---|---|
+| AC-1 | `[command]` | PASS |
+| AC-2 | `[command]` | PASS |
+| AC-3 | `[command]` | PASS |
+
+<!-- To reproduce: -->
+```bash
+[Verification commands in order]
+```
+
+</evidence>
+
+---
+
+## 4. What Remains Risky
+
+<residual_risk>
+  [Any risk accepted at Gate 3 that the next owner should be aware of.]
+  - [Risk item — mitigation or monitoring recommendation]
+</residual_risk>
+
+---
+
+## 5. Decisions & Assumptions
+
+<decisions_and_assumptions>
+  <!-- Only list decisions that affect future maintainers. Full record in decision.md. -->
+  - [Decision summary — why this approach was chosen over alternatives]
+</decisions_and_assumptions>
+
+---
+
+## 6. Next Action
+
+<next_action>
+  [What the next person or phase should do, if applicable. Otherwise: NONE.]
+</next_action>
+
+</handoff>

package/templates/process/_seeds/plan-template.md.seed

@@ -0,0 +1,135 @@
+# Plan: [PLAN-ID] [Task ID]
+
+<execution_plan task_id="[TASK-ID]" plan_id="[PLAN-ID]" version="2.0" framework="RIPER-5">
+
+<!-- PLAN PHASE. Plan artifacts only. No source-code changes. -->
+<plan_status>
+  <phase>PLAN</phase>
+  <last_updated></last_updated>
+</plan_status>
+
+---
+
+## 1. Input Artifacts
+
+<input_artifacts>
+  <task_spec>[Link to task.md]</task_spec>
+  <research>[Link to research.md]</research>
+  <decision>[Link to decision.md — DEC-ID, selected option]</decision>
+</input_artifacts>
+
+---
+
+## 2. Execution Constraints
+
+<!-- These constraints bind the Execute phase. Agent must not exceed them. -->
+<execution_constraints>
+  <allowed_files>
+    - `src/path/...` — [Reason]
+    - `tests/path/...` — [Reason]
+  </allowed_files>
+  <forbidden_files>
+    - `src/public-api/...` — [Not in scope]
+    - `schema/...` — [Schema changes require separate approval]
+  </forbidden_files>
+  <allowed_commands>
+    - `[test runner command]`
+    - `[lint/format command]`
+  </allowed_commands>
+  <restricted_operations>
+    - No DB migrations without explicit engineer approval.
+    - No new third-party dependencies without explicit engineer approval.
+  </restricted_operations>
+  <required_approvals>
+    - [List any mid-execute approvals required, e.g. before touching a shared module]
+  </required_approvals>
+</execution_constraints>
+
+---
+
+## 3. Slice Summary
+
+<slice_summary>
+
+| ID | Behavior | Boundary | Files | AC | Verifier | Risk | Mode | Rollback |
+|---|---|---|---|---|---|---|---|---|
+| S1 | | | | | | | | |
+| S2 | | | | | | | | |
+
+</slice_summary>
+
+---
+
+## 4. Slice Details
+
+<slices>
+
+  <slice id="S1">
+    <objective>[What behavior this slice delivers]</objective>
+    <change>[What specifically will be modified]</change>
+    <allowed_files>
+      - `src/path/file.py`
+    </allowed_files>
+    <acceptance_criteria>
+      - [ ] AC-N: [Criterion this slice satisfies]
+    </acceptance_criteria>
+    <verifier>
+      ```bash
+      # Command(s) that prove this slice is correct
+      ```
+    </verifier>
+    <expected_evidence>[What the verifier output must show]</expected_evidence>
+    <rollback_point>[What to undo if this slice fails — git stash / revert commit / flag]</rollback_point>
+    <stop_conditions>
+      - [Condition that requires halting and requesting human guidance]
+    </stop_conditions>
+  </slice>
+
+  <!-- Duplicate <slice> block for each additional slice -->
+
+</slices>
+
+---
+
+## 5. Scope Contract
+
+<scope_contract>
+  <allowed>
+    - [What the agent is permitted to change]
+  </allowed>
+  <forbidden>
+    - [What the agent must never touch during this plan]
+  </forbidden>
+</scope_contract>
+
+---
+
+## 6. Verification Matrix
+
+<!-- Populated during and after Execute phase -->
+<verification_matrix>
+
+| AC / Risk | Test / Command | Expected Evidence | Actual Result |
+|---|---|---|---|
+| AC-1 | | | |
+| AC-2 | | | |
+| AC-3 | | | |
+
+</verification_matrix>
+
+---
+
+## Gate 2 — Plan Approved
+
+<gate id="G2">
+  - [ ] Every slice has a defined verifier.
+  - [ ] Scope contract (allowed / forbidden) approved.
+  - [ ] Stop conditions defined per slice.
+  - [ ] Rollback point defined per slice.
+  - [ ] Allowed commands listed.
+  - [ ] Engineer approved.
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</execution_plan>

package/templates/process/_seeds/review-template.md.seed

@@ -0,0 +1,148 @@
+# Review: [REVIEW-ID] [Task ID]
+
+<review_artifact task_id="[TASK-ID]" review_id="[REVIEW-ID]" version="1.0" framework="RIPER-5">
+
+<!-- READ-ONLY PHASE. May run verification commands. No code fixes during review. -->
+<review_status>
+  <phase>REVIEW</phase>
+  <mode>READ-ONLY</mode>
+  <reviewer></reviewer>
+  <last_updated></last_updated>
+</review_status>
+
+---
+
+## 1. Review Scope
+
+<review_scope>
+  <task_spec>[Link to task.md]</task_spec>
+  <plan>[Link to plan.md]</plan>
+  <diff>[git diff range or PR link]</diff>
+  <tests>[Test suite path(s) executed]</tests>
+</review_scope>
+
+---
+
+## 2. Behavior Review
+
+<behavior_review>
+
+| AC | Expected | Actual | Evidence | Result |
+|---|---|---|---|---|
+| AC-1 | | | | PASS / FAIL |
+| AC-2 | | | | PASS / FAIL |
+| AC-3 | | | | PASS / FAIL |
+
+</behavior_review>
+
+---
+
+## 3. Architecture Review
+
+<architecture_review>
+  <dependency_direction>[Are imports flowing in the correct direction per architecture rules?]</dependency_direction>
+  <boundary_violations>[Any cross-boundary calls that violate the declared scope?]</boundary_violations>
+  <unnecessary_abstraction>[Any indirection added without justification?]</unnecessary_abstraction>
+  <unrelated_refactor>[Any changes not required by the task spec?]</unrelated_refactor>
+</architecture_review>
+
+---
+
+## 4. Data Review
+
+<data_review>
+  <transaction>[Transaction boundaries correct? No partial commits?]</transaction>
+  <consistency>[Data consistency guaranteed under concurrent writes?]</consistency>
+  <concurrency>[Race conditions, lock contention, optimistic locking?]</concurrency>
+  <migration>[Any schema changes backward-compatible?]</migration>
+  <constraints>[DB constraints respected?]</constraints>
+</data_review>
+
+---
+
+## 5. Security Review
+
+<security_review>
+  <authentication>[Auth context checked where required?]</authentication>
+  <authorization>[Permission checks in place?]</authorization>
+  <validation>[Input validation and sanitization complete?]</validation>
+  <secrets>[No secrets, tokens, or credentials in code or logs?]</secrets>
+  <injection>[SQL/command injection vectors covered?]</injection>
+  <sensitive_logging>[No PII or sensitive data written to logs?]</sensitive_logging>
+</security_review>
+
+---
+
+## 6. Regression Review
+
+<regression_review>
+  <existing_behavior>[Existing tests still passing? No previously green tests now failing?]</existing_behavior>
+  <backward_compatibility>[Public API / schema backward-compatible?]</backward_compatibility>
+  <existing_tests>[Were existing tests modified without justification?]</existing_tests>
+</regression_review>
+
+---
+
+## 7. Findings
+
+<findings>
+
+| ID | Category | Severity | Type | Evidence | File/Symbol | Required Action |
+|---|---|---|---|---|---|---|
+| F-1 | Behavior | HIGH | Confirmed Defect | | | |
+
+<!-- Category: Behavior | Architecture | Data | Security | Regression | Scope -->
+<!-- Severity: CRITICAL | HIGH | MEDIUM | LOW | INFO -->
+<!-- Type: Confirmed Defect | Risk requiring validation | Optional Improvement -->
+
+</findings>
+
+---
+
+## 8. Verification Matrix
+
+<verification_matrix>
+
+| AC / Risk | Verifier | Result | Evidence | Unverified |
+|---|---|---|---|---|
+| AC-1 | | PASS / FAIL | | |
+| AC-2 | | PASS / FAIL | | |
+| AC-3 | | PASS / FAIL | | |
+
+</verification_matrix>
+
+---
+
+## 9. Residual Risk
+
+<residual_risk>
+  [Risks that remain after review. Must be explicitly accepted before Gate 3 passes.]
+  -
+</residual_risk>
+
+---
+
+## 10. Review Decision
+
+<review_decision>
+  <!-- Choose one: PASS | CHANGES_REQUIRED | BLOCKED -->
+  <decision></decision>
+  <rationale></rationale>
+</review_decision>
+
+---
+
+## Gate 3 — Review Passed
+
+<gate id="G3">
+  - [ ] Full diff reviewed.
+  - [ ] All required evidence exists and is attached.
+  - [ ] All findings triaged (Confirmed Defects resolved or risk-accepted).
+  - [ ] Residual risk explicitly accepted.
+  - [ ] Review decision: PASS.
+  - [ ] Ready for handoff.
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</review_artifact>

package/templates/process/_seeds/state-template.md.seed

@@ -0,0 +1,149 @@
+# State: [TASK-ID]
+
+<loop_state task_id="[TASK-ID]" version="2.0" framework="RIPER-5">
+
+<!-- The persistent memory of the Execute loop. Update after every slice. -->
+<state_header>
+  <current_phase>EXECUTE</current_phase>  <!-- RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW -->
+  <current_gate>G2</current_gate>  <!-- G0 | G1 | G2 | G3 -->
+  <last_updated></last_updated>
+</state_header>
+
+---
+
+## 1. Task
+
+<task_ref>
+  <task_spec>[Link to task.md]</task_spec>
+  <plan>[Link to plan.md]</plan>
+</task_ref>
+
+---
+
+## 2. Goal & Invariants
+
+<goal_and_invariants>
+  <goal>[One-line restatement of the task goal]</goal>
+  <invariants>
+    - [Invariant 1 — must remain true throughout Execute]
+  </invariants>
+</goal_and_invariants>
+
+---
+
+## 3. Approved Decisions
+
+<approved_decisions>
+  <!-- Never re-open these. Read decision.md for full rationale. -->
+  - [DEC-ID]: [Decision summary — selected option X because Y]
+</approved_decisions>
+
+---
+
+## 4. Completed Slices
+
+<completed_slices>
+  <!-- Update after each slice verifier passes -->
+  | Slice | Status | Verifier Result | Evidence |
+  |---|---|---|---|
+  | S1 | | | |
+</completed_slices>
+
+---
+
+## 5. Current Slice
+
+<current_slice>
+  <id></id>
+  <objective></objective>
+  <status>IN_PROGRESS</status>  <!-- NOT_STARTED | IN_PROGRESS | VERIFYING | DONE | BLOCKED -->
+</current_slice>
+
+---
+
+## 6. Current Diff
+
+<current_diff>
+  <!-- Paste relevant `git diff` summary here after each slice to verify zero noise -->
+  ```diff
+  ```
+</current_diff>
+
+---
+
+## 7. Verification Evidence
+
+<verification_evidence>
+  <!-- Accumulate verifier output for each completed slice -->
+  ```
+  [Verifier command output]
+  ```
+</verification_evidence>
+
+---
+
+## 8. Failure Memory
+
+<!-- CRITICAL: Record every failure. Never retry the same approach twice. -->
+<failure_memory>
+
+  <failure id="F1">
+    <signature>[Unique error signature / symptom description]</signature>
+    <hypothesis>[What was believed to be the cause]</hypothesis>
+    <experiment>[What was tried]</experiment>
+    <result>[What actually happened]</result>
+    <must_not_repeat>[Specific action / assumption to never repeat]</must_not_repeat>
+  </failure>
+
+</failure_memory>
+
+---
+
+## 9. Retry Budget
+
+<retry_budget>
+  <allowed>3</allowed>
+  <used>0</used>
+  <remaining>3</remaining>
+  <!-- If remaining reaches 0: HALT and escalate to open_decisions in task.md -->
+</retry_budget>
+
+---
+
+## 10. Scope Changes
+
+<scope_changes>
+  <!-- Any approved deviations from the original plan.md scope contract -->
+  -
+</scope_changes>
+
+---
+
+## 11. Open Risks / Blockers
+
+<open_risks>
+  -
+</open_risks>
+
+---
+
+## 12. Next Action
+
+<next_action>
+  [Precise description of the very next step the agent must take.]
+</next_action>
+
+---
+
+## 13. Context Freshness Check
+
+<context_freshness>
+  <!-- Complete before continuing after any pause or context reload -->
+  - [ ] Active task spec re-read.
+  - [ ] Relevant source files re-read after last change.
+  - [ ] Plan.md current slice confirmed.
+  - [ ] Failure memory checked — no stale assumption being repeated.
+  - [ ] No unverified hypothesis being treated as confirmed fact.
+</context_freshness>
+
+</loop_state>