@phamvuhoang/otto-core 0.1.0

package/templates/afk.md

@@ -0,0 +1,21 @@
+{{ RESUME }}
+
+<commits>
+
+!?`git log -n 5 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<inputs>
+
+{{ INPUTS }}
+
+</inputs>
+
+@include:prompt.md

package/templates/apply-review.md

@@ -0,0 +1,71 @@
+{{ RESUME }}
+
+<commits>
+
+!?`git log -n 15 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<existing-followups>
+
+!?`cat ./.otto/review-followups.md|||_No follow-ups recorded yet._`
+
+</existing-followups>
+
+<review-doc>
+
+{{ INPUTS }}
+
+</review-doc>
+
+# APPLY REVIEW
+
+`<review-doc>` names a code-review document (a file path). `Read` it. It contains findings, usually with severities. Your job is to fix the actionable ones — ONE finding per iteration — and track the rest.
+
+When every actionable finding has been addressed (fixed, or already fixed in git, or recorded as a follow-up), output `<promise>NO MORE TASKS</promise>`.
+
+# TRIAGE
+
+Classify each finding (judge from the review's own language — severity labels, "follow-up", "operational", "cosmetic", "low risk"):
+
+- **Actionable** — a safe, in-scope correctness fix or cleanup (e.g. dead code, a clear bug, an incomplete cleanup). Fix it.
+- **Deferred / follow-up** — perf optimisation, operational steps, or anything large/out-of-scope (e.g. "re-reads N days every pull", "backfill mandatory at deploy"). Do NOT implement now; record it (below).
+- **Low / cosmetic / won't-fix** — note it in your commit body / final message with the reason; take no action.
+
+# RECONCILE BEFORE FIXING
+
+Before fixing a finding, check recent `git log` and the working tree — if it is already fixed, skip it (don't redo committed work). Treat the review as possibly stale.
+
+# FIX ONE FINDING
+
+Pick the highest-value actionable finding not yet addressed. Implement the fix. Run the feedback loops:
+
+### Frontend / Node
+
+- `pnpm run test`, `pnpm run typecheck`
+
+### Backend / Dotnet
+
+- `dotnet test`, `dotnet build`
+
+# RECORD FOLLOW-UPS
+
+For each Deferred / follow-up finding, append a terse entry to `./.otto/review-followups.md` (create it lazily). Use a dated `##` heading for this review, then one bullet per finding with its severity and why it is deferred. This file is git-tracked — commit it WITH the related fix (do not make a separate commit just for it).
+
+# COMMIT
+
+Make a single `git commit -am` with a short message:
+
+- Subject (≤72 chars): `fix(review): <what changed>`
+- Body: which finding (and its review section), key decision, and a one-line note of any follow-ups recorded.
+- No file lists, no `Co-Authored-By`.
+
+# FINAL RULES
+
+ONLY ADDRESS A SINGLE FINDING per iteration.

package/templates/ghafk-issue.md

@@ -0,0 +1,29 @@
+<commits>
+
+!?`git log -n 5 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<issue>
+
+!?`gh issue view "$OTTO_ISSUE" --json number,title,state|||Issue not found`
+
+Full issue body + comments spilled to: @spill?:issue.json=`gh issue view "$OTTO_ISSUE" --json number,title,body,comments,state|||[]`
+
+`Read` that file to get the full body and comments before acting on the issue.
+
+</issue>
+
+# THE TASK
+
+Work **only** on issue #{{ INPUTS }} (shown above). Do not list, triage, or pick from any other open issues — this run is scoped to a single issue.
+
+If issue #{{ INPUTS }} is already complete (closed, or there is no work left to do), output <promise>NO MORE TASKS</promise>.
+
+@include:ghprompt-workflow.md

package/templates/ghafk.md

@@ -0,0 +1,29 @@
+{{ RESUME }}
+
+<commits>
+
+!?`git log -n 5 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</commits>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<issues-summary>
+
+`gh issue list --state open --limit 50 --json number,title,labels`
+
+</issues-summary>
+
+<issues-full-file>
+
+Full issue bodies + comments spilled to: @spill?:issues.json=`gh issue list --state open --limit 50 --json number,title,body,labels,comments|||[]`
+
+Read that file with `Read` (use `offset`/`limit` if it is large) to get bodies and comments before picking a task. The `<issues-summary>` block above is the lean index for triage.
+
+</issues-full-file>
+
+@include:ghprompt.md

package/templates/ghprompt-workflow.md

@@ -0,0 +1,83 @@
+@include:superpowers.md
+
+# RECONCILE BEFORE SELECTING
+
+Before picking an issue, reconcile against reality: check recent `git log` and the working
+tree to see whether the work for an open issue is already implemented and committed. If it
+is, close/comment on the issue rather than redoing the work. Treat issue checklists as
+hints, not truth — committed code is done.
+
+# EXPLORATION
+
+Explore the repo.
+
+# IMPLEMENTATION
+
+Complete the task.
+
+# FEEDBACK LOOPS
+
+Before committing, run the feedback loops:
+
+### Frontend / Node
+
+- `pnpm run test` to run the tests
+- `pnpm run typecheck` to run the type checker
+
+### Backend / Dotnet
+
+- `dotnet test` to run the tests
+- `dotnet build` to type-check
+
+**If `dotnet test` or `dotnet build` fails with MSB3248** ("Could not resolve assembly reference" / "file is corrupt") — this is a known virtiofs/9p I/O quirk when the repo is mounted from the Windows host. It is NOT a code defect. Do not defer verification. Re-run with build outputs redirected to `/tmp` and parallelism disabled:
+
+```bash
+dotnet test <path-to-test-csproj> \
+  -m:1 \
+  /p:UseSharedCompilation=false \
+  /p:BuildInParallel=false \
+  /p:BaseIntermediateOutputPath=/tmp/otto-obj/$(basename <path-to-test-csproj> .csproj)/ \
+  /p:BaseOutputPath=/tmp/otto-bin/$(basename <path-to-test-csproj> .csproj)/
+```
+
+Only if that second attempt also fails may you defer and record the blocker in the commit message.
+
+# COMMIT
+
+Make a single `git commit -am` with a short message:
+
+- Subject line (≤72 chars): what changed
+- Optional body (≤3 bullets): key decision, blocker for next iteration
+- No file lists (git tracks them), no `Co-Authored-By`
+
+# THE ISSUE
+
+If the task is complete, close the original GitHub issue.
+
+If the task is not complete, leave a comment on the GitHub issue with what was done.
+
+# LEARNINGS
+
+The repo's accumulated learnings are in the `<learnings>` block — durable, reusable knowledge from prior iterations (conventions, gotchas, decisions and their why, dead ends). Consult it during EXPLORATION and IMPLEMENTATION so you don't relearn what's known or repeat a dead end.
+
+If, while doing the task, you discover a NEW durable, reusable learning — a repo convention, a non-obvious gotcha, a decision and its why, or a dead-end to avoid — append it tersely to the right section of `./.otto/LEARNINGS.md`. Create the file if it does not exist, with these four sections:
+
+```
+
+# Otto learnings
+
+## Conventions
+
+## Gotchas
+
+## Decisions
+
+## Dead ends
+
+```
+
+Dedupe against existing entries and prune anything no longer true. This file is committed WITH your task commit (it is git-tracked) — do NOT make a separate commit for it. The bar is durable AND reusable: do NOT record routine or one-off task details.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

package/templates/ghprompt.md

@@ -0,0 +1,39 @@
+# ISSUES
+
+Two views of open GitHub issues are provided at the start of context:
+
+- `<issues-summary>` — inline lean index (number, title, labels). Use this to triage and pick a task.
+- `<issues-full-file>` — path to a spilled JSON file containing bodies + comments. `Read` that file (with `offset`/`limit` if it is large) once you have picked an issue you want to act on.
+
+You will work on the AFK issues only, not the HITL ones. Label filtering uses the `labels` field in the summary.
+
+You've also been passed a file containing the last few commits. Review these to understand what work has been done.
+
+If all AFK tasks are complete, output <promise>NO MORE TASKS</promise>.
+
+# TASK SELECTION
+
+Pick the next task. Prioritize tasks in this order:
+
+1. Critical bugfixes
+2. Development infrastructure
+
+Getting development infrastructure like tests and types and dev scripts ready is an important precursor to building features.
+
+3. Tracer bullets for new features
+
+Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.
+
+TL;DR - build a tiny, end-to-end slice of the feature first, then expand it out.
+
+4. Polish and quick wins
+5. Refactors
+
+# RECONCILE BEFORE SELECTING
+
+Before picking an issue, reconcile against reality: check recent `git log` and the working
+tree to see whether the work for an open issue is already implemented and committed. If it
+is, close/comment on the issue rather than redoing the work. Treat issue checklists as
+hints, not truth — committed code is done.
+
+@include:ghprompt-workflow.md

package/templates/prompt.md

@@ -0,0 +1,97 @@
+# PLAN / PRD
+
+The plan and PRD are provided in the `<inputs>` block at the start of context — conventionally the paths to a plan file and a PRD file. `Read` them to get the work.
+
+You've also been passed the last few commits in `<commits>`. Review them to understand what work has already been done.
+
+Work through the plan/PRD tasks. If all of them are complete, output `<promise>NO MORE TASKS</promise>`.
+
+@include:superpowers.md
+
+# TASK SELECTION
+
+Pick the next task. Prioritize tasks in this order:
+
+1. Critical bugfixes
+2. Development infrastructure
+
+Getting development infrastructure like tests and types and dev scripts ready is an important precursor to building features.
+
+3. Tracer bullets for new features
+
+Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.
+
+TL;DR - build a tiny, end-to-end slice of the feature first, then expand it out.
+
+4. Polish and quick wins
+5. Refactors
+
+# RECONCILE BEFORE SELECTING
+
+Before picking a task, reconcile the plan against reality. Check recent `git log` and the
+working tree to see which tasks are **already implemented and committed**. Treat plan-file
+checkboxes as hints, NOT truth — code that is present and committed is done even if its box
+is unticked. Skip anything already done. When you complete or confirm a task, flip its
+checkbox as part of your commit so the plan converges to the truth.
+
+# EXPLORATION
+
+Explore the repo.
+
+# IMPLEMENTATION
+
+Complete the task.
+
+# FEEDBACK LOOPS
+
+Before committing, run the feedback loops:
+
+### Frontend / Node
+
+- `pnpm run test` to run the tests
+- `pnpm run typecheck` to run the type checker
+
+### Backend / Dotnet
+
+- `dotnet test` to run the tests
+- `dotnet build` to type-check
+
+# COMMIT
+
+Make a single `git commit -am` with a short message:
+
+- Subject line (≤72 chars): what changed
+- Optional body (≤3 bullets): key decision, blocker for next iteration
+- No file lists (git tracks them), no `Co-Authored-By`
+
+# RECORDING PROGRESS
+
+When a task is complete, record the outcome in your commit body, and update the plan file's status if it tracks one.
+
+If a task is not complete, record the blocker in the commit body so the next iteration can pick up where you left off.
+
+# LEARNINGS
+
+The repo's accumulated learnings are in the `<learnings>` block — durable, reusable knowledge from prior iterations (conventions, gotchas, decisions and their why, dead ends). Consult it during EXPLORATION and IMPLEMENTATION so you don't relearn what's known or repeat a dead end.
+
+If, while doing the task, you discover a NEW durable, reusable learning — a repo convention, a non-obvious gotcha, a decision and its why, or a dead-end to avoid — append it tersely to the right section of `./.otto/LEARNINGS.md`. Create the file if it does not exist, with these four sections:
+
+```
+
+# Otto learnings
+
+## Conventions
+
+## Gotchas
+
+## Decisions
+
+## Dead ends
+
+```
+
+Dedupe against existing entries and prune anything no longer true. This file is committed WITH your task commit (it is git-tracked) — do NOT make a separate commit for it. The bar is durable AND reusable: do NOT record routine or one-off task details.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

package/templates/review-lens.md

@@ -0,0 +1,41 @@
+<head>
+
+!?`git rev-parse HEAD|||(no commits)`
+
+</head>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<latest-diff>
+
+!?`git show --stat HEAD|||No diff`
+
+Full patch spilled to: @spill?:head.diff=`git show HEAD|||No diff body`
+
+Read that file with `Read` (use `offset`/`limit` for large diffs) before reviewing.
+
+</latest-diff>
+
+# REVIEWER — {{ LENS }} lens
+
+You review the most recent commit (HEAD) through ONE lens only: **{{ LENS }}**.
+
+- `correctness` — bugs, regressions, broken logic, unhandled edge cases.
+- `security` — input validation, secrets, injection, auth bypass.
+- `tests` — coverage gaps for the changed code; missing/weak assertions.
+
+If `<head>` shows `(no commits)`, output `<lens>SKIP</lens>` and stop.
+
+# OUTPUT
+
+List concrete findings for the **{{ LENS }}** lens only, each as `- <file>:<line> — <issue>`. Be terse. If nothing for this lens, output `none`.
+
+# RULES
+
+- READ-ONLY. Do **not** edit files (including `./.otto/LEARNINGS.md`). Do **not** commit. Do **not** run feedback loops.
+- Use the `<learnings>` block only to avoid flagging an already-accepted decision — never write to it.
+- Only the {{ LENS }} lens — ignore issues another lens owns.

package/templates/review-synth.md

@@ -0,0 +1,29 @@
+<head>
+
+!?`git rev-parse HEAD|||(no commits)`
+
+</head>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+# REVIEW SYNTHESIS
+
+An adversarial verifier already judged the lens findings and wrote `{{ FINDINGS_DIR }}verdicts.md`. `Read` that file. Only lines marked **`CONFIRMED`** are real defects to fix; ignore every `REJECTED` line. If the file says `none` or contains no `CONFIRMED` lines, there is nothing to fix.
+
+# ACTION
+
+1. Collect the `CONFIRMED` findings (already deduped and verified). If there are none, output `<review>OK</review>` and do **not** commit.
+2. Otherwise fix them in the working tree (only the latest commit's code — no unrelated changes), run the feedback loops:
+   - Frontend / Node: `pnpm run test`, `pnpm run typecheck`
+   - Backend / Dotnet: `dotnet test`, `dotnet build`
+     then make a SINGLE commit: `git commit -am "fix(review): <short reason>"` (subject ≤72 chars, no `Co-Authored-By`, no file lists). If a finding reflects a durable, reusable learning (e.g. a recurring defect class), you may also append it tersely to `./.otto/LEARNINGS.md` so it rides in this same commit.
+
+# RULES
+
+- Never amend the implementer's commit — always a new `fix(review):` commit.
+- Trust the verifier's verdicts — do not re-litigate `REJECTED` findings or hunt for new ones.
+- Single pass. Do not loop.

package/templates/review-verify.md

@@ -0,0 +1,52 @@
+<head>
+
+!?`git rev-parse HEAD|||(no commits)`
+
+</head>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<latest-diff>
+
+!?`git show --stat HEAD|||No diff`
+
+Full patch spilled to: @spill?:head.diff=`git show HEAD|||No diff body`
+
+Read that file with `Read` (use `offset`/`limit` for large diffs) before judging.
+
+</latest-diff>
+
+# ADVERSARIAL VERIFICATION
+
+Review lenses (correctness / security / tests) each examined HEAD and wrote findings to `{{ FINDINGS_DIR }}` — `Read` every `findings-*.md` file there.
+
+Your role is the **SKEPTIC**. The lenses are eager: many findings will be false positives, speculative, pre-existing, out of scope, or things this repo already accepts. Try to **REFUTE** each finding against the actual HEAD diff and the surrounding code before any of them earns a fix.
+
+For every distinct finding, decide:
+
+- **CONFIRMED** — you verified, against the real changed code, that it is a genuine defect introduced by THIS commit.
+- **REJECTED** — false positive, not reproducible, speculative, pre-existing (not introduced by HEAD), out of scope, or an already-accepted decision per `<learnings>`.
+
+Bias toward **REJECTED** when genuinely uncertain: this loop commits fixes with no human in the loop, so a wrong or noisy fix costs more than a missed nit.
+
+# OUTPUT
+
+Write your verdicts to `{{ FINDINGS_DIR }}verdicts.md`, one finding per line, deduped:
+
+```
+CONFIRMED — <file>:<line> — <issue> — <one line: why it is real>
+REJECTED — <file>:<line> — <issue> — <one line: why not>
+```
+
+If the lenses produced no findings at all, write a single line: `none`.
+
+End your reply with a one-line tally: `<verify>C confirmed, R rejected</verify>`.
+
+# RULES
+
+- READ-ONLY except for writing `verdicts.md`. Do **not** edit tracked files. Do **not** commit. Do **not** run feedback loops.
+- Judge only HEAD's changes. Ignore pre-existing issues the commit did not introduce.

package/templates/review.md

@@ -0,0 +1,62 @@
+<head>
+
+!?`git rev-parse HEAD|||(no commits)`
+
+</head>
+
+<recent-commits>
+
+!?`git log -n 3 --format="%H%n%ad%n%B---" --date=short|||No commits found`
+
+</recent-commits>
+
+<learnings>
+
+!?`cat ./.otto/LEARNINGS.md|||_No learnings recorded yet._`
+
+</learnings>
+
+<latest-diff>
+
+!?`git show --stat HEAD|||No diff`
+
+Full patch spilled to: @spill?:head.diff=`git show HEAD|||No diff body`
+
+Read that file with `Read` (use `offset`/`limit` for large diffs) before reviewing.
+
+</latest-diff>
+
+# REVIEWER
+
+You review the most recent commit (HEAD) produced by the implementer.
+
+If `<head>` shows `(no commits)` or HEAD is unchanged from the previous iteration, output `<review>SKIP</review>` and stop without making any commit.
+
+# CHECK
+
+1. Bugs and regressions
+2. Test coverage gaps for the changed code
+3. Style violations vs `CLAUDE.md` or project conventions
+4. Security issues (input validation, secrets, injection, auth bypass)
+5. Half-finished implementations, dead code, leftover TODO from this commit
+
+# ACTION
+
+If defects found:
+
+- Fix them directly in the working tree.
+- Run feedback loops:
+  - Frontend / Node: `pnpm run test`, `pnpm run typecheck`
+  - Backend / Dotnet: `dotnet test`, `dotnet build`
+- Commit with `git commit -am "fix(review): <short reason>"`. Subject ≤72 chars. No `Co-Authored-By` line. No file lists.
+
+If clean: output `<review>OK</review>` and stop. Do NOT commit.
+
+If the review surfaced a durable, reusable learning (e.g. a recurring defect class worth remembering), append it tersely to the right section of `./.otto/LEARNINGS.md` as part of your `fix(review):` commit — never as a separate commit, and only when you are already committing a fix.
+
+# RULES
+
+- Only review the latest commit. Do not touch unrelated code.
+- Do not add new features or refactor beyond the defect fix.
+- Never amend the implementer's commit — always a new `fix(review):` commit.
+- Single review pass. Do not loop.

package/templates/superpowers.md

@@ -0,0 +1,70 @@
+# SUPERPOWERS WORKFLOW (always on)
+
+Run this gate before the work described below. It routes every task through
+brainstorm → spec → plan → TDD, adapting to how clear the input is. There is
+NO human available during this run: act autonomously and record your reasoning
+instead of waiting for approval.
+
+If the `superpowers:brainstorming`, `superpowers:writing-plans`, and
+`superpowers:test-driven-development` skills are available, invoke them for
+fuller guidance. If they are not installed, follow the inline protocol below —
+it is self-contained.
+
+## 0. Resolve the task key
+
+- GitHub issue run → task-key = `issue-<issue number>`.
+- Plan/PRD run → task-key = a stable slug from the primary plan-file basename
+  (e.g. `docs/plans/foo.md` → `foo`). If inputs are inline text, use a short
+  kebab-case of the task title.
+
+Spec path: `.otto/specs/<task-key>-design.md`
+Plan path: `.otto/plans/<task-key>.md`
+
+## 1. CLARITY GATE
+
+Check whether `.otto/specs/<task-key>-design.md` already exists.
+
+- **Spec exists** → skip brainstorming. Read the spec and
+  `.otto/plans/<task-key>.md`, pick the next unchecked task, and go to
+  TDD IMPLEMENT (section 3). If every plan task is checked AND the feedback
+  loops pass, output `<promise>NO MORE TASKS</promise>`.
+- **No spec** → judge the input's clarity. It is UNCLEAR if any of: no
+  plan/PRD provided; a vague directive ("make it better"); missing acceptance
+  criteria; multiple plausible interpretations; internal contradictions.
+  - Clear enough → go straight to TDD IMPLEMENT (section 3). Optionally jot a
+    short plan to `.otto/plans/<task-key>.md` first.
+  - Unclear → AUTONOMOUS BRAINSTORM (section 2).
+
+## 2. AUTONOMOUS BRAINSTORM (no human in the loop)
+
+Play both sides of a brainstorming session:
+
+1. List the clarifying questions a brainstorming session would ask (purpose,
+   scope, constraints, success criteria, edge cases).
+2. Answer each one yourself with the most reasonable default given the repo's
+   existing patterns. Prefer the simplest viable option (YAGNI).
+3. Write `.otto/specs/<task-key>-design.md` containing: Problem, Approach, an
+   **Assumptions** section listing each `question → chosen answer → rationale`,
+   and Testing notes.
+4. Write `.otto/plans/<task-key>.md` as an ordered checklist of bite-sized,
+   testable tasks (one `- [ ]` per task).
+5. Do NOT wait for approval — the written assumptions are the record.
+
+If a question is genuinely blocking (needs a secret or a human-only decision),
+record the blocker in the spec and the commit body, take the safest assumption,
+and make forward progress on the unblocked parts. Never stop and wait — this is
+AFK.
+
+## 3. TDD IMPLEMENT
+
+Implement exactly one task, test-first:
+
+1. Write a failing test that pins the intended behavior.
+2. Run it; confirm it fails for the right reason.
+3. Write the minimal code to make it pass.
+4. Run the feedback loops described below until green.
+5. Update `.otto/plans/<task-key>.md`: check off the task. If a new durable,
+   reusable learning emerged, append it to `.otto/LEARNINGS.md`.
+
+Commit the code, the updated spec/plan, and LEARNINGS together in the single
+task commit described below — do NOT make separate commits for them.