Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,14 +49,15 @@ a `NN-` prefix (for example `00-project.mdc`) and are never generated or pruned.
``Use when the user runs `/<name>` or `$<name>`, ...`` so every agent's
invocation syntax matches.
2. Put anything long in `.agents/skills/<name>/references/`.
3. Run `bash .agents/scripts/sync-skills.sh`.
4. Add `.codex/skills/<name>/agents/openai.yaml` if the skill should show up in
the Codex skill picker.
3. Optionally author `agents/openai.yaml` in the canonical skill directory.
The sync copies it to the Codex pointer for skill-picker discovery.
4. Run `bash .agents/scripts/sync-skills.sh`.

## Current skills

| Skill | Purpose |
| --- | --- |
| `maintain` | One serialized maintenance/product cycle, recovery and delivery |
| `commit` | Branch checks, conventional commits, push, PR |
| `review-self` | Self-review loop over the current work until stable |
| `review-pr` | PR review findings and review-comment handling |
Expand Down
10 changes: 8 additions & 2 deletions .agents/scripts/sync-skills.sh
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,10 @@ codex_notes() {

- Sibling skills written as `$name` are Codex skills; invoke them directly.
- This skill's Codex interface metadata lives in `agents/openai.yaml`.
- For any interval or recurring step, use a Codex automation. Never emulate it
with `sleep`, `while true`, or a detached background process.
- Use supported bounded tool waits for an active task's review/check interval.
Do not create an automation to monitor one task to completion. Standing daily
project work may use one Codex automation when the user requested it.
Never emulate recurrence with shell sleep loops or detached background jobs.
EOF
}

Expand Down Expand Up @@ -114,6 +116,10 @@ for dir in "$canonical_dir"/*/; do
write_pointer .codex "Codex" codex_notes "$name" "$title" "$description"
write_pointer .grok "Grok" grok_notes "$name" "$title" "$description"
write_cursor_pointer "$name" "$title" "$description"
if [ -f "$dir/agents/openai.yaml" ]; then
mkdir -p ".codex/skills/$name/agents"
cp "$dir/agents/openai.yaml" ".codex/skills/$name/agents/openai.yaml"
fi
echo "generated: $name"
done

Expand Down
82 changes: 40 additions & 42 deletions .agents/skills/loop-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Run BooKoo's complete change-to-merge loop from the latest origin/m

Own one BooKoo change from a fresh `main` baseline through a verified merge.
Delegate to the sibling skill that owns a procedure instead of restating it.
Only the steps no sibling skill owns — external reviewer requests, polling, the
Only the steps no sibling skill owns — polling, the
regression gates, and the merge — are specified here.

## Load The Workflows
Expand All @@ -20,17 +20,22 @@ Read before acting:
An explicit invocation authorizes the in-scope commit, push, PR creation, review
replies, thread resolution, and merge for this task. It does not authorize
`$release-update`, store submission, Expo updates, running data migrations
against production Convex, or unrelated cleanup.
against production Convex, or unrelated cleanup. Existing standing authority in
AGENTS.md still applies when this is a `$maintain` continuation.

## 1. Start From Current Main

1. Snapshot `git status --short --branch`. Preserve every existing change.
2. For a new task, require a clean worktree, then `git fetch origin`, switch to
`main`, and `git pull --ff-only origin main`.
3. Confirm local `main` equals `origin/main`, then create a semantic branch
using the naming rules in `$commit` — `feat/`, `bugfix/`, `docs/`,
`refactor/`, `test/`, or `chore/`. Never a tool or vendor prefix.
4. Record the starting main SHA. The implementation diff must descend from it.
2. Resolve the canonical repository and remote first. For `$maintain`, it is
`hyodotdev/BooKoo`; an ops clone's `origin` can point elsewhere. Fetch that
remote's main explicitly and record its full SHA as the integration base.
3. Require a clean task worktree before claiming new work. Branch from that
fetched main using `$commit` naming rules. Fast-forward an existing local
main only when its lineage matches and no other task uses it; otherwise
preserve it and use an isolated checkout/worktree based on canonical main.
4. Record the remote name and main SHA. Use that remote/main throughout this
loop, including PRs, ancestry checks, push and final readback; `origin/main`
in examples is not authority to integrate into a different repository.

If invoked for work already in progress, treat it as a resumed loop. Do not
stash, reset, switch branches, or discard anything. Verify the merge base and
Expand Down Expand Up @@ -71,15 +76,11 @@ Follow `$commit` with push and PR:
- Push the semantic branch and open an English PR against `main`.
- Apply 1–3 existing repository labels; never invent new ones.

`$commit` does not request external reviewers, so this loop does it. Request
whichever review bot the repository actually has configured, and never block on
the response: post the request, then run the exact-head `$review-self` fallback
in the same round so the head has review coverage immediately. If the bot
reports later on that same head, handle its findings as a new round.

Do not substitute a different review bot for one that is unavailable, and never
count a silently-ignored reviewer request as coverage — the
`requested_reviewers` API accepts unknown reviewers and adds nobody.
Use `$review-self` for change reviews. Do not request Muse or substitute another
external reviewer. Inspect existing human/automation feedback through `$review-pr`;
report self-review honestly without claiming independent coverage. The single-round
fallback below handles feedback during polling; it does not replace step 3's two
clean snapshots separated by five minutes.

When the pushed head is identical to the diff step 3 already stabilized, record
that coverage against the head SHA instead of repeating the round. Any later
Expand All @@ -90,8 +91,8 @@ clean review coverage.

## 5. Poll Until The Exact Head Is Clean

Run `$review-pr` immediately, then re-enter it every five minutes through the
product's recurring wake-up mechanism. `loop-review` is the only polling owner;
Run `$review-pr` immediately, then re-enter it every five minutes through
supported bounded tool waits in the active task. `loop-review` is the only polling owner;
`review-pr` performs one pass per round.

Each round:
Expand All @@ -102,20 +103,17 @@ Each round:
comment with the plain commit hash, and resolve only the threads you replied
to with a fix.
3. Rerun the checks the batch affects plus everything previously failing.
4. After a head change, redo step 4 for the new SHA — re-request the reviewer
4. After a head change, redo step 4 for the new SHA — rerun the affected self-review
and re-establish head coverage, since the push invalidated the previous
round.
5. Keep polling while CI is pending or a reviewer has reported findings you have
not handled. A missing reviewer response never holds the loop open. Do not
rerun expensive unchanged local checks on a no-op poll, and never retrigger a
review bot on a no-op.
5. Keep polling while CI or actionable feedback is pending. Do not rerun
expensive unchanged local checks on a no-op poll or request review bots.

Clean means all of these hold for the same head SHA:

- zero unresolved actionable review threads;
- the head has review coverage — either the external reviewer reported on it
with nothing actionable left, or the exact-head `$review-self` fallback ran
clean;
- the head has clean `$review-self` coverage and step 3's two separated clean
snapshots still cover this exact tree; a single fallback is insufficient;
- every required CI check is terminal and successful;
- the PR is mergeable and carries every required update from `main`;
- the worktree is clean and the final diff has been reread.
Expand All @@ -139,13 +137,11 @@ sign-in providers, invite deep links, app lock, receipt photo capture,
notifications, `app.config.ts`, `plugins/`, `android/`, `ios/`, or dependency
changes that reach the runtime.

When it is required, **stop without merging even if the PR is otherwise
clean**. Report the scenarios the diff implicates and hand back to the user. Two
things clear the gate, and both are recorded on the PR first:

1. An `$e2e-test` run covering the implicated scenarios, with its result posted.
2. An explicit written waiver from the user in this conversation, naming what is
waived and why. Record it verbatim on the PR.
When required, run `$e2e-test` for the implicated scenarios and record its
result on the PR before merging. Missing or failed native gates block merging.
Only an explicit written owner waiver naming the omitted checks and reason can
waive a missing gate; record it verbatim. Do not request a waiver for checks that
can be completed under standing authority.

Absence of an objection is not a waiver, and the loop never grants itself one.
Green CI is not a substitute — CI does not launch a simulator, add a ledger
Expand All @@ -158,18 +154,20 @@ that justify it; silence reads as an untested merge.
## 7. Merge And Close The Loop

Immediately before merging, refetch the PR and confirm its head still equals the
clean reviewed SHA. Squash merge with branch deletion unless a stricter policy
applies. Never bypass branch protection or merge a stale, pending, or failing
head.
clean reviewed SHA. Follow root AGENTS.md: strict nonforce fast-forward only.
Confirm remote main is an ancestor of the reviewed head. Inspect current protection and
rulesets first. If permitted, push the reviewed head to main without force and
verify GitHub marks the PR merged. If protection requires a different method,
report the conflict without bypassing it. Do not silently substitute squash or
merge a stale, pending, or failing head.

After merge:

1. Confirm the PR state is `MERGED` and record the merge commit.
2. Delete the reviewer-trigger comments this loop posted and any terminal
"review skipped/unavailable" notices. Never delete human comments, inline
replies, or substantive review feedback.
3. Switch to `main` and fast-forward from `origin/main` when that cannot disturb
other work.
2. Preserve substantive review discussion and evidence; no reviewer-trigger
comments are needed for self-review.
3. Fast-forward the matching local integration checkout only when that cannot
disturb other work. Preserve any legacy ops main with a different history.
4. Report the PR, merge commit, final checks, review coverage, gate results, and
anything skipped. Do not release or deploy unless separately requested.

Expand Down
121 changes: 121 additions & 0 deletions .agents/skills/maintain/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
name: maintain
description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes.
---

# Maintain

Coordinate existing skills; keep their implementation and gates authoritative.
Standing owner authority and its exceptions live in
[AGENTS.md](../../../AGENTS.md#autonomous-operation). Current scope, evidence and
resume point live only in [STATUS](../../../.notes/STATUS.md); decisions and
visual direction stay in their existing `.notes/` owners.

## Acquire Before Acting

1. Verify the checkout and canonical remote `https://github.com/hyodotdev/BooKoo`.
An older ops checkout may have unrelated history: preserve it and use the
existing public worktree/checkout. Discover actual remote names; do not assume
`origin` points to the public repo. Inspect Git status without exposing `.local/`.
2. Acquire the host-wide OS lock with
`python3 .agents/skills/maintain/scripts/coordinator.py hold --owner <run-id>`
in a managed interactive terminal. Keep that terminal/process alive throughout
the cycle. Require its `ACQUIRED` result; exit code 75 means another run owns
the coordinator: report contention and exit without starting any mutations.
A new checkout without the skill must acquire the same lock from an existing
checkout before creating branches or installing anything.
3. `status` probes the actual kernel lock, not PID guesses. The lock is shared
across worktrees and clones on this host. If the holder dies, the OS releases
it; retain the lock file/inode and acquire it normally. Never unlink it or kill
an unfamiliar holder. A live orphan needs inspection of its terminal/run before
stopping it. Across hosts require shared scheduler concurrency; this local
lock alone is insufficient. Never enable a second host coordinator.
4. Immediately before each mutation after a wait, ensure the holder terminal is
alive and `status` still reports the same owner/PID. If ownership is lost,
stop mutations and reacquire before reconstructing remote state.
5. Release by sending a newline to the holder terminal only after saving the
resume point and stopping owned transient processes. Do not leave a holder
running across a saved external/PENDING checkpoint.

## Recover And Select

- Read STATUS, current owner goal, root/directory rules, package/lockfile, current
workflows and relevant sibling skills. Fetch the canonical main; inspect open
PRs, exact CI and release tags/runs. Recover existing task branches first.
Preserve unrelated edits; isolate new work rather than stashing or resetting.
- Recover a pending/failed release before starting a dependent bundle. Query each
platform separately: source/tag, artifact/build ID, internal upload, review,
approval and public availability are different facts. A successful GitHub
Release run only proves dispatch. After timeout query remote state before retry.
- If authentication/external review is the only blocker, record exact prerequisites
and continue independent maintenance; never duplicate an upload or submission.
- With no new goal, choose one evidenced bug/security/performance/compatibility/CI/
documentation fix. With a product goal, define flows, acceptance and order;
record new direction proposals instead of implementing them without an owner goal.
- Before edits, claim one branch in STATUS with purpose, dependency order,
acceptance, base SHA and expected delivery path. Bound the bundle: newly found
unrelated updates go to the next cycle unless urgent or a real prerequisite.
Use official release notes and compatibility sources for upgrades, preserve
`.ncurc.json` exclusions and patch purposes, and review cumulative native changes.

## Execute Through Existing Owners

| Need | Reuse |
| --- | --- |
| Aggregate growth evidence / one growth experiment | `$analyze` / `$grow`, only when relevant to the owner's goal |
| Implementation to integration | `$loop-review` with `$commit`, `$review-self`, `$review-pr` |
| Lists, Convex, rollups | `$perf-audit` |
| UI refinement and implicated device scenarios | `$loop-ui` / `$e2e-test` |
| Marketing version / explicit build-floor decision | `$update-version` |
| Backend, OTA, candidate, store and follow-up | `$release-update` and purchase acceptance matrix |

Keep one coordinator and one review polling owner. Perform edits, installs,
hook installation, prebuild, integration and delivery sequentially. Self-review
must retain two complete clean snapshots at least five minutes apart covering
the final tree, terminal CI and resolved feedback. A single polling fallback
cannot replace this. Do not invoke external reviewers or call self-review
independent. Use bounded tool waits in the current task, not another automation
watching this PR. Save PENDING when the runtime cannot continue.

Run current CI's mandatory commands: frozen copyfile install, `bun lint:all`,
`bun typecheck`, coverage tests, full-history secret scan and the separate
anonymous local Convex 100k budget job. The budget child success marker is
required; exit 0 from its parent is insufficient. General Jest may skip that
suite. Prefer exact-head CI for isolated budget/history evidence; never borrow
an old SHA's result for changed inputs. Local QA must remove inherited deployment
credentials and use the existing anonymous runner. Store bounded logs/artifacts
on the verified DevLogs volume on the owner's host; no internal bulk fallback.
Record PASS / FAIL / PENDING / N/A per check and invalidate affected evidence
when files change. Required premerge native gates remain mandatory.

Read branch protection/rulesets and root merge policy immediately before
integration; use nonforce fast-forward when permitted, never implicit squash or
an admin bypass. Recheck remote main ancestry and exact reviewed head. Verify
GitHub recognizes the PR merge and check the exact main CI/deploy job afterwards.

## Decide Delivery And Resume

- Docs, skills and development-tooling-only bundles finish with integration and
exact-main verification. Do not dispatch OTA or store tags for them.
- Runtime bundles deliver only when their acceptance and applicable source,
native, purchase and old-client/backend compatibility gates pass. Compare
cumulative changes since each platform's actual last public artifact.
- Reuse the existing backend CI, Patch OTA or Codemagic/local EAS native path;
no EAS cloud builds. Require backend/index readiness before a dependent client.
Verify target binary/version/fingerprint before asserting OTA compatibility.
Internal candidate uploads precede final candidate acceptance; public review/
rollout waits for it. Do not raise force-update floors with routine releases.
- Before release record last healthy source/artifact and a supported recovery
path. Verify deployed functions and relevant smoke/error signals afterwards
without gathering private ledgers. On regression stop dependent releases and
use a verified compatible fix, supported OTA recovery or rollout halt.
- Limit the same failure to three cause-based attempts (or a stricter sibling
limit). New evidence must justify a retry. Save exact PR/base/head/merge,
checks, deployment states, external conditions and next runnable action in
STATUS/PR; no duplicate backlog/history file or date-only commits. GitHub PR
metadata owns final merge SHA, avoiding a SHA-only follow-up commit.
- Daily scheduling belongs to the supported app scheduler, once at 09:00
Asia/Seoul after the first verified cycle. Inspect existing schedules before
creating/updating one; no recursive runner or schedule proliferation. A local
run needs the host awake, app running, project access, credentials and DevLogs
for bulk work. If unavailable, report `$maintain` as the supported manual entry.
4 changes: 4 additions & 0 deletions .agents/skills/maintain/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Maintain BooKoo"
short_description: "Run one serialized maintenance and delivery cycle"
default_prompt: "Use $maintain to recover BooKoo's current work and complete one verified maintenance cycle."
Loading
Loading