diff --git a/Brewfile b/Brewfile index 5f2265c..076382f 100644 --- a/Brewfile +++ b/Brewfile @@ -19,9 +19,12 @@ tap "mike-engel/jwt-cli" # For Git -> Confluence Documentation #tap "kovetskiy/mark" tap "datadog-labs/pack" +tap "atlassian/homebrew-acli", trusted:true # Binaries +# Atlassian/Jira cli +brew "acli" # A GitHub Action Runner for local development brew "act" # A Github Action validator diff --git a/README.md b/README.md index 331be8b..ba6b02b 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,20 @@ cd dotfiles/install While running install and at iTerm, you SHOULD be asked to run `p10k configure`. Once here go to iTerm +### Moving to a new Mac + +Some files hold settings for one machine and stay out of this repo. Before running the install script: + +1. Copy `~/.site` from the old Mac (see [Site settings](#site-settings-site)). It can hold tokens, so move it through a password manager, not a repo. +2. Clone the private Claude config repo and list it in `CLAUDE_EXTRA_DIRS` (see [Claude Code](#claude-code)). + +During the install script, the macOS step: + +- rebuilds the Dock and sets the system keyboard shortcuts +- asks whether to use AeroSpace. With AeroSpace, workspaces 1-9 are on Cmd-1..9 and the config is `aerospace/aerospace.toml`. Without it, the script waits while you add 9 desktops in Mission Control, sets Cmd-1..9 to switch between them, and stages the Rectangle config for import. + +Log out and back in afterwards so every setting takes effect. + ### iTerm * Run p10k configure (if not already prompted) @@ -126,25 +140,29 @@ This will override any more general config in ~/.gitconfig ### PR tracking -`bin/pr-state-record`, `bin/pr-status`, and `bin/pr-state-hook` keep track of the pull requests you open, grouped by ticket. +`bin/pr-state-record` and `bin/pr-status` keep track of the pull requests you open, grouped by ticket. - `pr-state-record [--ticket ABC-1234] [--title "Ticket title"] [--desc "Row description"]` records a PR in `~/.local/state/pr/.md`, one file per ticket and one table row per PR. Re-running it for the same PR updates the row. -- `pr-status` shows the review and merge status of every open PR, from one GitHub GraphQL query. Open PRs carry badges for draft, merge conflicts, behind base, CI failing or pending, and unresolved review threads. `--comments` lists each unresolved thread under its PR. `pr-status --all` includes merged and closed PRs, and `--since YYYY-MM-DD` includes those merged or closed on or after the date. `--markdown` prints "Merged / closed" and "Open" sections without colors, with the unresolved threads, for pasting into notes such as a standup. Each run refreshes the state files and moves a ticket's file to `~/.local/state/pr/archive/` once all its PRs are merged or closed and the newest one closed more than `PR_EXPIRE_DAYS` (default 14) days ago. -- `pr-state-hook` is a Claude Code `PostToolUse` hook for Bash that records every PR created with `gh pr create`. Register it in `~/.claude/settings.json`: - -```json -"hooks": { - "PostToolUse": [ - { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bash ~/.local/bin/pr-state-hook" }] } - ] -} -``` +- `pr-status` shows the review and merge status of every open PR, from one GitHub GraphQL query. Open PRs carry badges for draft, merge conflicts, behind base, CI failing or pending, and unresolved review threads. `--comments` lists each unresolved thread under its PR. `pr-status --all` includes merged and closed PRs, and `--since YYYY-MM-DD` includes those merged or closed on or after the date. `--markdown` prints "Merged / closed" and "Open" sections without colors, with the unresolved threads, for pasting into notes such as a standup; ticket keys matching `PR_TICKET_PATTERN` become Obsidian `[[wikilinks]]`. Each run refreshes the state files and moves a ticket's file to `~/.local/state/pr/archive/` once all its PRs are merged or closed and the newest one closed more than `PR_EXPIRE_DAYS` (default 14) days ago. -Site-specific settings belong in `~/.site`, which `zshrc` sources: +The ticket settings live in `~/.site` (see [Site settings](#site-settings-site)). Without `PR_TICKET_PATTERN`, PRs go to the `housekeeping` ticket unless you pass `--ticket`. + +### Claude Code + +The `claude_config` step of the install script sets up `~/.claude`: + +- `~/.claude/CLAUDE.md` is a local file on each machine. The installer adds an import of the shared rules in `ai/claude/CLAUDE.md`, plus one import for each private repo. Notes for one machine only can go directly in this file. +- Each skill in `ai/skills/` is linked into `~/.claude/skills/`, alongside any skills already there. +- Private config (the Obsidian vault map, company-specific workflows, private skills) lives in a private repo such as `ai-private`. List its path in `CLAUDE_EXTRA_DIRS`; the installer imports the repo's `claude/CLAUDE.md` and links its `skills/`, `commands/`, and `agents/`. It warns when `CLAUDE_EXTRA_DIRS` is unset; set it to `""` on a machine without private config. +- The shared rules keep project plans, notes, and proofs in the Obsidian vault at `$OBSIDIAN_VAULT`, and working files in a `tmp/` folder at the project root, which `git/gitignore_global` ignores in every repo. + +### Site settings (`~/.site`) + +`zshrc` sources `~/.site` for settings that differ between machines: ```bash -export PR_TICKET_PATTERN='ABC-[0-9]+' # ticket keys to detect in branch, title, and body -export PR_JIRA_URL='https://example.atlassian.net' # adds a Jira link to each ticket file +export PR_TICKET_PATTERN='ABC-[0-9]+' # ticket keys to detect in branch, title, and body +export PR_JIRA_URL='https://example.atlassian.net' # adds a Jira link to each ticket file +export OBSIDIAN_VAULT="$HOME/obsidian/Second Brain" # Obsidian vault for Claude project notes +export CLAUDE_EXTRA_DIRS="$HOME/src/github/ai-private" # space-separated private Claude config repos ``` - -Without `PR_TICKET_PATTERN`, PRs go to the `housekeeping` ticket unless you pass `--ticket`. diff --git a/ai/claude/CLAUDE.md b/ai/claude/CLAUDE.md index 404547d..0547988 100644 --- a/ai/claude/CLAUDE.md +++ b/ai/claude/CLAUDE.md @@ -15,13 +15,15 @@ - When the user says "pushed", follow the `update-pr` skill: check for an existing PR and offer to create or update it. Always ask first. ## Workflow +- Work one step at a time: agree on a step, make its changes, then stop and ask before starting the next. - Use absolute paths in shell commands, staying inside the project directory. Prefer a tool's directory flag (`make -C `, `go test -C `, `git -C `); when a tool has none, prefix with `cd &&`. -- Build, lint, test, clean, and dependency steps go through the project's own wrapper (Makefile, scripts), not the underlying tool directly. If the wrapper can't do something, propose a fix to it rather than working around it. +- When the project has a wrapper (Makefile, scripts), build, lint, test, clean, and dependency steps go through it, not the underlying tool directly. If the wrapper can't do something, propose a fix to it rather than working around it. +- `cp`, `mv`, and `rm` are aliased to prompt first (`-i`). In shell commands an unanswered prompt skips the operation: a copy reports "not overwritten" and later steps run on an empty or stale file, and `rm` leaves the file in place. Use `command cp -f` / `command mv -f` / `command rm` or `cat src > dst`, check the result before writing over or deleting an original, and back up tracked files with `git show HEAD:`. Scripts run as `bash script.sh` don't load the aliases. - Never change anything outside the current repo without explicit permission. That includes `~/.claude` (memory, CLAUDE.md), other directories, and remote systems (deploys, pushes, APIs). The repo's Obsidian project folder (below) is the one standing exception. ## Project notes (Obsidian) -- Plans, prompts, notes, and proofs for a repo go in the Obsidian vault, not the repo. The vault is `$OBSIDIAN_VAULT` (default `~/Second Brain`). -- The project folder and client for a repo come from the vault map imported in `~/.claude/CLAUDE.md`. When a repo has no entry, ask which folder to use and offer to add a row to the map. +- Plans, prompts, notes, and proofs for a repo go in the Obsidian vault, not the repo. The vault is `$OBSIDIAN_VAULT` (default `~/obsidian/Second Brain`). +- The project folder and company for a repo come from the vault map imported in `~/.claude/CLAUDE.md`. When a repo has no entry, ask which folder to use and offer to add a row to the map. - A note that isn't about the current repo (a call, a personal note) doesn't follow the map: ask which folder it belongs in. The machine or repo says nothing about whose note it is. - Layout: `/{plans,prompts,notes,proofs}/YYYY-MM-DD-.md`. Proofs are evidence: test output, screenshots, before/after captures. - Every file starts with this frontmatter: @@ -29,7 +31,7 @@ --- type: plan # plan | prompt | note | proof project: - client: + company: repo: created: YYYY-MM-DD tags: [claude, plan] # second tag matches type @@ -38,11 +40,11 @@ ## Scratch files - Throwaway files (one-off downloads, probes, intermediate output): system `/tmp`. -- Verify checkouts and other working files that aren't project notes: `tmp/` at the project root, gitignored (add `/tmp/` to `.gitignore` before writing there). +- Verify checkouts and other working files that aren't project notes: `tmp/` at the project root. The global gitignore ignores it in every repo, so nothing needs adding to the repo's `.gitignore`. - If unsure where something belongs, ask. ## PR tracking -- PRs are tracked per ticket in `~/.local/state/pr/` by `pr-state-record`. A hook records PRs from `gh pr create`. For a PR opened another way, or one that moves to another ticket or needs a better description, run `pr-state-record [--ticket X] [--desc "..."]`. Never edit the state files by hand. +- PRs are tracked per ticket in `~/.local/state/pr/` by `pr-state-record`. After opening a PR, or when one moves to another ticket or needs a better description, run `pr-state-record [--ticket X] [--desc "..."]`. Never edit the state files by hand. - For PR status, run `pr-status` (open PRs) or `pr-status --all` instead of querying `gh` per PR. ## Writing diff --git a/ai/skills/update-pr/SKILL.md b/ai/skills/update-pr/SKILL.md index 22edf10..e52086e 100644 --- a/ai/skills/update-pr/SKILL.md +++ b/ai/skills/update-pr/SKILL.md @@ -18,6 +18,20 @@ gh pr view --json number,url,body 2>&1 Always ask before acting. Never update silently. +## Tracking + +After creating or updating a PR, make sure `pr-status` tracks it under the right ticket: + +```bash +pr-status --all | grep -F '' +``` + +- Not listed → `pr-state-record --ticket --desc ""` +- Listed under the wrong ticket, or its description no longer matches the PR → `pr-state-record [--ticket ] [--desc "..."]` with the fields to fix +- Listed and correct → nothing to do + +Never edit the state files by hand. + ## PR Body Structure ### Required sections diff --git a/bin/pr-state-hook b/bin/pr-state-hook deleted file mode 100755 index 46bdacf..0000000 --- a/bin/pr-state-hook +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env bash -# pr-state-hook — Claude Code PostToolUse hook for Bash. When the command ran `gh pr create`, -# records the new PR's URL (from the command's output) with pr-state-record. -# Reads the hook payload as JSON on stdin. Prints a systemMessage when it records a PR. -set -uo pipefail - -payload=$(cat) -command=$(jq -r '.tool_input.command // ""' <<<"$payload") -[[ "$command" == *"gh pr create"* ]] || exit 0 - -output=$(jq -r '[.tool_response.stdout, .tool_response.output, (.tool_response | strings)] | map(select(. != null)) | join("\n")' <<<"$payload") -url=$(grep -oE 'https://github\.com/[^/[:space:]]+/[^/[:space:]]+/pull/[0-9]+' <<<"$output" | tail -1) -[[ -n "$url" ]] || exit 0 - -if result=$("$HOME/.local/bin/pr-state-record" "$url" 2>&1); then - jq -n --arg m "$result" '{systemMessage: $m}' -else - jq -n --arg m "pr-state-hook: could not record $url: $result" '{systemMessage: $m}' -fi diff --git a/bin/pr-status b/bin/pr-status index 5af7d52..41afa19 100755 --- a/bin/pr-status +++ b/bin/pr-status @@ -15,14 +15,15 @@ # --all also merged and closed PRs # --since also PRs merged or closed on or after the date # --comments list each unresolved review thread under its PR -# --markdown markdown without colors, in "Merged / closed" and "Open" sections; implies --comments +# --markdown markdown without colors, in "Merged / closed" and "Open" sections, with ticket keys +# as [[wikilinks]]; implies --comments set -euo pipefail STATE_DIR="${PR_STATE_DIR:-$HOME/.local/state/pr}" RECORD="${PR_STATE_RECORD:-$HOME/.local/bin/pr-state-record}" EXPIRE_DAYS="${PR_EXPIRE_DAYS:-14}" -usage() { sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 1; } +usage() { sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'; exit 1; } SHOW_ALL=false MARKDOWN=false @@ -188,8 +189,9 @@ expired() { ' "$1" } -# ticket_heading FILE — prints the ticket heading: the file's header line, with the ticket key -# linked to its jira URL in markdown mode. +# ticket_heading FILE — prints the ticket heading: the file's header line. In markdown mode a key +# matching PR_TICKET_PATTERN is an Obsidian [[wikilink]] to the ticket's note, followed by its jira +# link. ticket_heading() { local header jira key header=$(head -1 "$1" | sed 's/^# //') @@ -199,7 +201,13 @@ ticket_heading() { fi jira=$(sed -n 's/^- jira: //p' "$1") key="${header%% — *}" - if [[ -n "$jira" ]]; then + if [[ -n "${PR_TICKET_PATTERN:-}" ]] && grep -qxiE "$PR_TICKET_PATTERN" <<<"$key"; then + if [[ -n "$jira" ]]; then + echo "- [[${key}]] ([Jira](${jira})) — ${header#* — }" + else + echo "- [[${key}]] — ${header#* — }" + fi + elif [[ -n "$jira" ]]; then echo "- [${key}](${jira}) — ${header#* — }" else echo "- ${header}" diff --git a/git/gitignore_global b/git/gitignore_global index 366a385..70c1dfb 100644 --- a/git/gitignore_global +++ b/git/gitignore_global @@ -2,3 +2,5 @@ *.sw[op] CLAUDE.local.md **/.claude/settings.local.json +# Project-root scratch space (see ai/claude/CLAUDE.md) +/tmp/ diff --git a/install/install.sh b/install/install.sh index 462c80d..50f441d 100755 --- a/install/install.sh +++ b/install/install.sh @@ -105,9 +105,12 @@ claude_config() { claude_import '~/dotfiles/ai/claude/CLAUDE.md' link_items ~/dotfiles/ai/skills ~/.claude/skills - # Private sources listed in CLAUDE_EXTRA_DIRS in ~/.site + # Private sources listed in CLAUDE_EXTRA_DIRS in ~/.site. Setting it to "" opts out. local extra_dirs dir kind - extra_dirs=$(zsh -c 'source ~/.site 2>/dev/null; print -r -- $CLAUDE_EXTRA_DIRS' 2>/dev/null) + if ! extra_dirs=$(zsh -c 'source ~/.site 2>/dev/null; (( ${+CLAUDE_EXTRA_DIRS} )) || exit 1; print -r -- $CLAUDE_EXTRA_DIRS' 2>/dev/null); then + logger "WARNING: CLAUDE_EXTRA_DIRS is not set in ~/.site, so no private Claude config (vault map) is imported." + logger "Clone ai-private and set CLAUDE_EXTRA_DIRS to its path, or set it to \"\" to skip, then re-run." + fi for dir in $extra_dirs; do if [ ! -d "$dir" ]; then logger "Skipping $dir: not found (clone it, then re-run)"