Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
154
reference/atuin-18.16.1/.claude/skills/hunk/SKILL.md
Executable file
154
reference/atuin-18.16.1/.claude/skills/hunk/SKILL.md
Executable file
@@ -0,0 +1,154 @@
|
||||
---
|
||||
name: hunk-review
|
||||
description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively.
|
||||
---
|
||||
|
||||
# Hunk Review
|
||||
|
||||
Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT run `hunk diff`, `hunk show`, or other interactive commands directly. Use `hunk session *` CLI commands to inspect and control live sessions through the local daemon.
|
||||
|
||||
If no session exists, ask the user to launch Hunk in their terminal first.
|
||||
|
||||
## Workflow
|
||||
|
||||
```text
|
||||
1. hunk session list # find live sessions
|
||||
2. hunk session get --repo . # inspect path / repo / source
|
||||
3. hunk session review --repo . --json # inspect file/hunk structure first
|
||||
4. hunk session review --repo . --include-patch --json # opt into raw diff text only when needed
|
||||
5. hunk session context --repo . # check current focus when needed
|
||||
6. hunk session navigate ... # move to the right place
|
||||
7. hunk session reload -- <command> # swap contents if needed
|
||||
8. hunk session comment add ... # leave one review note
|
||||
9. hunk session comment apply ... # apply many agent notes in one stdin batch
|
||||
```
|
||||
|
||||
## Session selection
|
||||
|
||||
Most session commands accept:
|
||||
|
||||
- `--repo <path>` -- match the live session by its current loaded repo root (most common)
|
||||
- `<session-id>` -- match by exact ID (use when multiple sessions share a repo)
|
||||
- If only one session exists, it auto-resolves
|
||||
|
||||
`reload` also supports:
|
||||
|
||||
- `--session-path <path>` -- match the live Hunk window by its current working directory
|
||||
- `--source <path>` -- load the replacement `diff` / `show` command from a different directory
|
||||
|
||||
Use `--source` only for advanced reloads where the live session you want to control is not already associated with the checkout you want to load next. For a normal worktree session, prefer selecting it directly with `--repo /path/to/worktree`.
|
||||
|
||||
## Commands
|
||||
|
||||
### Inspect
|
||||
|
||||
```bash
|
||||
hunk session list [--json]
|
||||
hunk session get (--repo . | <id>) [--json]
|
||||
hunk session context (--repo . | <id>) [--json]
|
||||
hunk session review (--repo . | <id>) [--json] [--include-patch]
|
||||
```
|
||||
|
||||
- `get` shows the session `Path`, `Repo`, and `Source`, which helps when choosing between `--repo` and `--session-path`
|
||||
- `Repo` is what `--repo` matches; `Path` is what `--session-path` matches
|
||||
- `review --json` returns file and hunk structure by default; add `--include-patch` only when a caller truly needs raw unified diff text
|
||||
|
||||
### Navigate
|
||||
|
||||
Absolute navigation requires `--file` and exactly one of `--hunk`, `--new-line`, or `--old-line`:
|
||||
|
||||
```bash
|
||||
hunk session navigate --repo . --file src/App.tsx --hunk 2
|
||||
hunk session navigate --repo . --file src/App.tsx --new-line 372
|
||||
hunk session navigate --repo . --file src/App.tsx --old-line 355
|
||||
```
|
||||
|
||||
Relative comment navigation jumps between annotated hunks and does not require `--file`:
|
||||
|
||||
```bash
|
||||
hunk session navigate --repo . --next-comment
|
||||
hunk session navigate --repo . --prev-comment
|
||||
```
|
||||
|
||||
- `--hunk <n>` is 1-based
|
||||
- `--new-line` / `--old-line` are 1-based line numbers on that diff side
|
||||
- Use either `--next-comment` or `--prev-comment`, not both
|
||||
|
||||
### Reload
|
||||
|
||||
Swaps the live session's contents. Pass a Hunk review command after `--`:
|
||||
|
||||
```bash
|
||||
hunk session reload --repo . -- diff
|
||||
hunk session reload --repo . -- diff main...feature -- src/ui
|
||||
hunk session reload --repo . -- show HEAD~1
|
||||
hunk session reload --repo . -- show HEAD~1 -- README.md
|
||||
hunk session reload --repo /path/to/worktree -- diff
|
||||
hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff
|
||||
```
|
||||
|
||||
- Always include `--` before the nested Hunk command
|
||||
- `--repo` or `<session-id>` usually selects the session you want
|
||||
- `--source` is advanced: it does not select the session; it only changes where the replacement review command runs
|
||||
- If the live session is already showing the target worktree, prefer `hunk session reload --repo /path/to/worktree -- diff`
|
||||
- `--session-path` targets the live window when you need to keep session selection separate from reload source
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"] [--focus]
|
||||
printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin [--focus]
|
||||
hunk session comment list --repo . [--file README.md]
|
||||
hunk session comment rm --repo . <comment-id>
|
||||
hunk session comment clear --repo . --yes [--file README.md]
|
||||
```
|
||||
|
||||
- `comment add` is best for one note; `comment apply` is best when an agent already has several notes ready
|
||||
- `comment add` requires `--file`, `--summary`, and exactly one of `--old-line` or `--new-line`
|
||||
- `comment apply` payload items require `filePath`, `summary`, and exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`
|
||||
- `comment apply` reads a JSON batch from stdin and validates the full batch before mutating the live session
|
||||
- Pass `--focus` when you want to jump to the new note or the first note in a batch
|
||||
- `comment list` and `comment clear` accept optional `--file`
|
||||
- Quote `--summary` and `--rationale` defensively in the shell
|
||||
|
||||
## New files in working-tree reviews
|
||||
|
||||
`hunk diff` includes untracked files by default. If the user wants tracked changes only, reload with `--exclude-untracked`:
|
||||
|
||||
```bash
|
||||
hunk session reload --repo . -- diff --exclude-untracked
|
||||
```
|
||||
|
||||
## Guiding a review
|
||||
|
||||
The user may ask you to walk them through a changeset or review code using Hunk. Start with `hunk session review --json` to understand the file/hunk structure without inflating agent context, then use `--include-patch` only for the files you truly need to read in raw diff form. Use `context` and `navigate` to line up the user's current view before adding comments.
|
||||
|
||||
Your role is to narrate: steer the user's view to what matters and leave comments that explain what they're looking at.
|
||||
|
||||
Typical flow:
|
||||
|
||||
1. Load the right content (`reload` if needed)
|
||||
2. Navigate to the first interesting file / hunk
|
||||
3. Add a comment explaining what's happening and why
|
||||
4. If you already have several notes ready, prefer one `comment apply` batch over many separate shell invocations
|
||||
5. Summarize when done
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Work in the order that tells the clearest story, not necessarily file order
|
||||
- Navigate before commenting so the user sees the code you're discussing
|
||||
- Use `comment apply` for agent-generated batches and `comment add` for one-off notes
|
||||
- Use `--focus` sparingly when the note itself should actively steer the review
|
||||
- Keep comments focused: intent, structure, risks, or follow-ups
|
||||
- Don't comment on every hunk -- highlight what the user wouldn't spot themselves
|
||||
|
||||
## Common errors
|
||||
|
||||
- **"No visible diff file matches ..."** -- the file is not in the loaded review. Check `context`, then `reload` if needed.
|
||||
- **"No active Hunk sessions"** -- ask the user to open Hunk in their terminal.
|
||||
- **"Multiple active sessions match"** -- pass `<session-id>` explicitly.
|
||||
- **"No active Hunk session matches session path ..."** -- for advanced split-path reloads, verify the live window `Path` via `hunk session get` or `list`, then use `--session-path`.
|
||||
- **"Pass the replacement Hunk command after `--`"** -- include `--` before the nested `diff` / `show` command.
|
||||
- **"Pass --stdin to read batch comments from stdin JSON."** -- `comment apply` only reads its batch payload from stdin.
|
||||
- **"Specify exactly one navigation target"** -- pick one of `--hunk`, `--old-line`, or `--new-line`.
|
||||
- **"Specify either --next-comment or --prev-comment, not both."** -- choose one comment-navigation direction.
|
||||
269
reference/atuin-18.16.1/.claude/skills/release/SKILL.md
Executable file
269
reference/atuin-18.16.1/.claude/skills/release/SKILL.md
Executable file
@@ -0,0 +1,269 @@
|
||||
---
|
||||
name: release
|
||||
description: >
|
||||
Orchestrate a multi-step Atuin CLI release — version bumping, changelog
|
||||
generation, PR creation, tagging, and crates.io publishing. Invoke with
|
||||
/release or /release <version>.
|
||||
disable-model-invocation: true
|
||||
argument-hint: [version]
|
||||
---
|
||||
|
||||
# Atuin CLI Release
|
||||
|
||||
You are orchestrating a release of the Atuin CLI. Follow the steps below
|
||||
**in order**, pausing at each checkpoint for user confirmation. Do not skip
|
||||
steps or combine them.
|
||||
|
||||
## Current State
|
||||
|
||||
- Workspace version: !`sed -n '/^\[workspace\.package\]/,/^\[/s/^version = "\(.*\)"/\1/p' Cargo.toml`
|
||||
- Latest tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "none"`
|
||||
- Suggested next version: !`git-cliff --bumped-version 2>/dev/null | sed 's/^v//' || echo "(unknown)"`
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Check Dependencies
|
||||
|
||||
Verify these tools are installed: `git`, `gsed`, `cargo`, `gh`, `git-cliff`.
|
||||
|
||||
Use `command -v` for each. If any are missing, report which ones and stop.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Determine Version
|
||||
|
||||
The target version may be provided as `$ARGUMENTS`. If it's empty, use
|
||||
AskUserQuestion to ask for the new version (show the current state above
|
||||
for reference).
|
||||
|
||||
After determining the version:
|
||||
- If it contains a `-` (e.g. `18.15.0-beta.1`), it is a **prerelease**.
|
||||
Note this — it affects changelog and publish behavior later.
|
||||
- Show the user: `current → new` and whether it's a prerelease.
|
||||
- **Checkpoint:** Ask the user to confirm before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Set Up Working Directory
|
||||
|
||||
Clone a fresh copy into a temp directory:
|
||||
|
||||
```bash
|
||||
WORKDIR=$(mktemp -d)
|
||||
git clone git@github.com:atuinsh/atuin.git "$WORKDIR"
|
||||
```
|
||||
|
||||
Print the working directory path so the user can find it if needed.
|
||||
All subsequent Bash commands run from `$WORKDIR`.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Create Branch & Update Versions
|
||||
|
||||
1. Create a release branch named after the version (no `v` prefix):
|
||||
`git checkout -b <VERSION>`
|
||||
|
||||
2. Replace the old version with the new one in all `Cargo.toml` files.
|
||||
**Escape dots** in the old version so sed treats them literally:
|
||||
|
||||
```bash
|
||||
VERSION_PATTERN="${OLD_VERSION//./\\.}"
|
||||
find . -type f -name 'Cargo.toml' -not -path './.git/*' \
|
||||
-exec gsed -i "s/$VERSION_PATTERN/$NEW_VERSION/g" {} \;
|
||||
```
|
||||
|
||||
3. Run `cargo check` to update `Cargo.lock`.
|
||||
|
||||
4. Show `git diff --stat` and the version-related lines from the diff:
|
||||
```bash
|
||||
git diff --unified=0 -- '*.toml' | grep -E '^\+.*version' | grep -v '^\+\+\+'
|
||||
```
|
||||
|
||||
5. Verify the workspace version was actually updated by re-reading it
|
||||
from `Cargo.toml`.
|
||||
|
||||
6. **Checkpoint:** Show the diff summary and ask the user to confirm the
|
||||
version changes look correct.
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Update Changelog
|
||||
|
||||
The changelog strategy differs for prereleases vs stable releases:
|
||||
|
||||
- **Prerelease:** Maintain a running `## [unreleased]` section containing
|
||||
all changes since the last stable release. Use:
|
||||
`git-cliff --unreleased --strip all`
|
||||
(cliff.toml's `ignore_tags` already ignores beta/alpha tags, so
|
||||
`--unreleased` spans back to the last stable release automatically.)
|
||||
|
||||
- **Stable release:** Generate a versioned entry that replaces the
|
||||
`[unreleased]` section. Use:
|
||||
`git-cliff --unreleased --tag "v<VERSION>" --strip all`
|
||||
|
||||
Then update `CHANGELOG.md`:
|
||||
|
||||
1. If an existing `## [unreleased]` or `## [Unreleased]` section exists,
|
||||
**remove it entirely** (the heading and all content up to the next
|
||||
`## ` heading).
|
||||
|
||||
2. Insert the new entry before the first existing `## ` version heading.
|
||||
|
||||
3. **Checkpoint:** Read and display the new changelog entry to the user.
|
||||
Ask if they want any edits. If so, make the requested changes using
|
||||
the Edit tool. Repeat until they're satisfied.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Commit & Push
|
||||
|
||||
Stage all changes and commit:
|
||||
|
||||
```
|
||||
chore(release): prepare for release <VERSION>
|
||||
```
|
||||
|
||||
Push the branch with `--set-upstream origin`.
|
||||
|
||||
---
|
||||
|
||||
## Step 7 — Create PR & Wait for Merge
|
||||
|
||||
### Create the PR
|
||||
|
||||
Extract the changelog entry body (everything between the new `## ` heading
|
||||
and the next one) for the PR description.
|
||||
|
||||
For prereleases, the heading to match is `## [unreleased]`.
|
||||
For stable releases, it's `## <VERSION>` (escape dots in the awk pattern).
|
||||
|
||||
Create the PR:
|
||||
```bash
|
||||
gh pr create \
|
||||
--title "chore(release): prepare for release <VERSION>" \
|
||||
--body "<body with changelog>" \
|
||||
--repo atuinsh/atuin
|
||||
```
|
||||
|
||||
Show the PR URL to the user.
|
||||
|
||||
### Wait for merge
|
||||
|
||||
Start a **persistent Monitor** that polls the PR status every 30 seconds.
|
||||
The monitor script must:
|
||||
- **Only emit output** on meaningful state changes: all checks green, PR
|
||||
merged, or PR closed. Silent polls keep the monitor quiet and avoid
|
||||
flooding notifications.
|
||||
- Handle transient API errors gracefully (don't crash on a single failure)
|
||||
- Exit 0 on `MERGED`, exit 1 on `CLOSED`
|
||||
|
||||
The rollup mixes two entry shapes: `CheckRun` entries use `status` +
|
||||
`conclusion`, while `StatusContext` entries use `state`. A check counts
|
||||
as "passing" when it's in a terminal state with a non-failing outcome.
|
||||
Treat `SUCCESS`, `SKIPPED`, and `NEUTRAL` as passing — some release
|
||||
workflows (e.g. `announce`, `build-global-artifacts`) are conditional
|
||||
and report `SKIPPED` on non-tag events, which is expected, not a
|
||||
failure.
|
||||
|
||||
Example monitor script (substitute the actual PR number):
|
||||
```bash
|
||||
checks_passed=false
|
||||
while true; do
|
||||
json=$(gh pr view PR_NUM --repo atuinsh/atuin --json state,statusCheckRollup 2>/dev/null) || { sleep 30; continue; }
|
||||
state=$(echo "$json" | jq -r '.state')
|
||||
case "$state" in
|
||||
MERGED) echo "PR #PR_NUM has been merged!"; exit 0 ;;
|
||||
CLOSED) echo "PR #PR_NUM was closed without merging."; exit 1 ;;
|
||||
esac
|
||||
# Only notify once when all checks reach a terminal passing state.
|
||||
# CheckRun entries carry `status`/`conclusion`; StatusContext entries
|
||||
# carry `state`. SKIPPED and NEUTRAL count as passing.
|
||||
if [ "$checks_passed" = false ]; then
|
||||
counts=$(echo "$json" | jq -r '
|
||||
[.statusCheckRollup[]?] as $all
|
||||
| ($all | map(select(
|
||||
(.status == "COMPLETED" and (.conclusion | IN("SUCCESS","SKIPPED","NEUTRAL")))
|
||||
or .state == "SUCCESS"
|
||||
)) | length) as $passing
|
||||
| ($all | map(select(
|
||||
(.status == "COMPLETED" and (.conclusion | IN("FAILURE","TIMED_OUT","CANCELLED","ACTION_REQUIRED","STALE")))
|
||||
or (.state | IN("FAILURE","ERROR"))
|
||||
)) | length) as $failing
|
||||
| "\($all | length) \($passing) \($failing)"
|
||||
' 2>/dev/null)
|
||||
read -r total passing failing <<<"$counts"
|
||||
if [ "${failing:-0}" -gt 0 ] 2>/dev/null; then
|
||||
echo "PR #PR_NUM has $failing failing check(s) — investigate before merging."
|
||||
checks_passed=true # don't re-notify
|
||||
elif [ "${total:-0}" -gt 0 ] 2>/dev/null && [ "$total" = "$passing" ]; then
|
||||
echo "All $total checks passed on PR #PR_NUM — ready to merge!"
|
||||
checks_passed=true
|
||||
fi
|
||||
fi
|
||||
sleep 30
|
||||
done
|
||||
```
|
||||
|
||||
Tell the user to go review and merge the PR. While the monitor runs, you
|
||||
can respond to other questions — the monitor notifications will arrive
|
||||
asynchronously.
|
||||
|
||||
When the monitor reports `MERGED`, proceed to the next step.
|
||||
If it reports `CLOSED`, inform the user and stop the release.
|
||||
|
||||
---
|
||||
|
||||
## Step 8 — Tag Release
|
||||
|
||||
Back in the working directory:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
git tag "v<VERSION>"
|
||||
git push --tags
|
||||
```
|
||||
|
||||
Tell the user the tag was pushed and the release CI workflow has been
|
||||
triggered.
|
||||
|
||||
---
|
||||
|
||||
## Step 9 — Publish to crates.io
|
||||
|
||||
**If this is a prerelease**, skip this step entirely and tell the user.
|
||||
|
||||
**If this is a stable release**, ask the user whether to publish.
|
||||
|
||||
If yes, publish each crate **in dependency order** using `--no-verify`
|
||||
(the code already passed CI, and verification fails when crates.io
|
||||
hasn't indexed a freshly-published dependency yet):
|
||||
|
||||
```
|
||||
atuin-common, atuin-client, atuin-ai, atuin-dotfiles, atuin-history,
|
||||
atuin-nucleo/matcher, atuin-nucleo, atuin-daemon, atuin-kv,
|
||||
atuin-scripts, atuin-server-database, atuin-server-postgres,
|
||||
atuin-server-sqlite, atuin-server, atuin-pty-proxy, atuin
|
||||
```
|
||||
|
||||
For each crate, run from `crates/<name>`:
|
||||
```bash
|
||||
cargo publish --no-verify 2>&1
|
||||
```
|
||||
|
||||
If it fails with "already uploaded", report it as a skip (not an error) —
|
||||
some crates like `atuin-nucleo` are versioned independently and may
|
||||
already be published at their current version.
|
||||
|
||||
If it fails for any other reason, stop and report the error.
|
||||
|
||||
---
|
||||
|
||||
## Completion
|
||||
|
||||
Summarize what was done:
|
||||
- Version released
|
||||
- PR URL
|
||||
- Tag name
|
||||
- Which crates were published (if any)
|
||||
- Working directory path and how to clean it up (`rm -rf`)
|
||||
Reference in New Issue
Block a user