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
3 changes: 3 additions & 0 deletions Brewfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
50 changes: 34 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,20 @@

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:

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 102 Warning

Expected: 80; Actual: 102

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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 149 Warning

Expected: 80; Actual: 149
2. Clone the private Claude config repo and list it in `CLAUDE_EXTRA_DIRS` (see [Claude Code](#claude-code)).

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 109 Warning

Expected: 80; Actual: 109

During the install script, the macOS step:

- rebuilds the Dock and sets the system keyboard shortcuts

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 281 Warning

Expected: 80; Actual: 281

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash

Log out and back in afterwards so every setting takes effect.

### iTerm

* Run p10k configure (if not already prompted)
Expand Down Expand Up @@ -126,25 +140,29 @@

### 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 102 Warning

Expected: 80; Actual: 102

- `pr-state-record <pr-url> [--ticket ABC-1234] [--title "Ticket title"] [--desc "Row description"]` records a PR in `~/.local/state/pr/<TICKET>.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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 824 Warning

Expected: 80; Actual: 824

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`.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 174 Warning

Expected: 80; Actual: 174

### 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 227 Warning

Expected: 80; Actual: 227
- Each skill in `ai/skills/` is linked into `~/.claude/skills/`, alongside any skills already there.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 100 Warning

Expected: 80; Actual: 100

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 370 Warning

Expected: 80; Actual: 370
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 210 Warning

Expected: 80; Actual: 210

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: asterisk; Actual: dash Warning

Expected: asterisk; Actual: dash

### 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

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 103 Warning

Expected: 80; Actual: 103
export PR_JIRA_URL='https://example.atlassian.net' # adds a Jira link to each ticket file

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 91 Warning

Expected: 80; Actual: 91
export OBSIDIAN_VAULT="$HOME/obsidian/Second Brain" # Obsidian vault for Claude project notes

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 94 Warning

Expected: 80; Actual: 94
export CLAUDE_EXTRA_DIRS="$HOME/src/github/ai-private" # space-separated private Claude config repos

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 100 Warning

Expected: 80; Actual: 100
```

Without `PR_TICKET_PATTERN`, PRs go to the `housekeeping` ticket unless you pass `--ticket`.
14 changes: 8 additions & 6 deletions ai/claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,23 @@
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Lists should be surrounded by blank lines Warning

Lists should be surrounded by blank lines

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 105 Warning

Expected: 80; Actual: 105
- Use absolute paths in shell commands, staying inside the project directory. Prefer a tool's directory flag (`make -C <abs path>`, `go test -C <abs path>`, `git -C <abs path>`); when a tool has none, prefix with `cd <abs path> &&`.
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 235 Warning

Expected: 80; Actual: 235
- `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:<path>`. Scripts run as `bash script.sh` don't load the aliases.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 479 Warning

Expected: 80; Actual: 479
- 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`).

Check warning

Code scanning / Markdownlint (reported by Codacy)

Lists should be surrounded by blank lines Warning

Lists should be surrounded by blank lines

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 154 Warning

Expected: 80; Actual: 154
- 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.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 187 Warning

Expected: 80; Actual: 187
- 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: `<project folder>/{plans,prompts,notes,proofs}/YYYY-MM-DD-<slug>.md`. Proofs are evidence: test output, screenshots, before/after captures.
- Every file starts with this frontmatter:
```yaml
---
type: plan # plan | prompt | note | proof
project: <repo name>
client: <client from the vault map, or personal>
company: <company from the vault map, or personal>
repo: <abs repo path>
created: YYYY-MM-DD
tags: [claude, plan] # second tag matches type
Expand All @@ -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`.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 196 Warning

Expected: 80; Actual: 196
- 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 <url> [--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 <url> [--ticket X] [--desc "..."]`. Never edit the state files by hand.

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 254 Warning

Expected: 80; Actual: 254

Check warning

Code scanning / Markdownlint (reported by Codacy)

Lists should be surrounded by blank lines Warning

Lists should be surrounded by blank lines
- For PR status, run `pr-status` (open PRs) or `pr-status --all` instead of querying `gh` per PR.

## Writing
Expand Down
14 changes: 14 additions & 0 deletions ai/skills/update-pr/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,20 @@

Always ask before acting. Never update silently.

## Tracking

After creating or updating a PR, make sure `pr-status` tracks it under the right ticket:

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 88 Warning

Expected: 80; Actual: 88

```bash
pr-status --all | grep -F '<PR url>'
```

- Not listed → `pr-state-record <url> --ticket <KEY> --desc "<one-line summary>"`
- Listed under the wrong ticket, or its description no longer matches the PR → `pr-state-record <url> [--ticket <KEY>] [--desc "..."]` with the fields to fix

Check warning

Code scanning / Markdownlint (reported by Codacy)

Expected: 80; Actual: 157 Warning

Expected: 80; Actual: 157
- Listed and correct → nothing to do

Never edit the state files by hand.

## PR Body Structure

### Required sections
Expand Down
19 changes: 0 additions & 19 deletions bin/pr-state-hook

This file was deleted.

18 changes: 13 additions & 5 deletions bin/pr-status
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/^# //')
Expand All @@ -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}"
Expand Down
2 changes: 2 additions & 0 deletions git/gitignore_global
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,5 @@
*.sw[op]
CLAUDE.local.md
**/.claude/settings.local.json
# Project-root scratch space (see ai/claude/CLAUDE.md)
/tmp/
7 changes: 5 additions & 2 deletions install/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand Down
Loading