mirror of
https://github.com/prdlk/dotfiles.git
synced 2026-11-04 03:47:36 +00:00
config(git,claude,ssh): templated gitconfig; claude settings/commands/hooks/skills; ssh config
gitconfig: name/email from chezmoi data, gh credential helper by PATH lookup (portable to darwin). claude: no credentials, history, projects, sessions, or plugin caches. ssh config as private_ (0600). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Prad NukalaandClaude Fable 5 committed
1 parent
3c691e8dc5
commit
20891f3910
476 files changed
+59086
-7
No files matched your search
@@ -0,0 +1,118 @@
|
||||
---
|
||||
description: Recursively implement all pending beads issues until every one is closed with tests passing, builds succeeding, requirements met, and blockers cleared
|
||||
argument-hint: [optional: priority filter e.g. "p0-p2" | epic id | "dry-run"]
|
||||
allowed-tools: Bash(bd:*), Bash(git:*), Bash(go:*), Bash(pnpm:*), Bash(cargo:*), Bash(make:*), Read, Write, Edit, Glob, Grep, Task
|
||||
---
|
||||
|
||||
# /bd-drain — Recursive Beads Completion Workflow
|
||||
|
||||
Drain the beads backlog to zero. Work every ready issue to full completion, unblock dependent issues as they clear, and repeat until no open, actionable work remains. Arguments: `$ARGUMENTS` (optional priority filter like `p0-p2`, an epic ID to scope to, or `dry-run` to plan without executing).
|
||||
|
||||
## Phase 0 — Session Bootstrap
|
||||
|
||||
1. Run `bd dolt pull` to sync beads state from remote.
|
||||
2. Run `bd prime` if context was compacted or this is a fresh session.
|
||||
3. Run `bd doctor` — if sync problems or missing hooks are reported, fix them before proceeding.
|
||||
4. Run `bd stats` and record the baseline: open / in_progress / blocked counts. This is the burn-down target.
|
||||
5. Run `bd memories drain` and `bd memories <project keyword>` to load any prior insights about this workflow or codebase gotchas.
|
||||
6. Detect the project's verification commands by inspecting the repo (Makefile, Taskfile, turbo.json, package.json scripts, go.mod, Cargo.toml). Record:
|
||||
- **TEST_CMD** (e.g. `go test ./...`, `pnpm turbo test`, `cargo test`)
|
||||
- **BUILD_CMD** (e.g. `go build ./...`, `pnpm turbo build`)
|
||||
- **LINT_CMD** if present (e.g. `golangci-lint run`, `pnpm lint`)
|
||||
7. Run TEST_CMD and BUILD_CMD once **before touching anything** to establish a green baseline. If the baseline is already red, create a P0 bug with `bd create` describing the pre-existing failure and fix it first — never build on a broken base.
|
||||
|
||||
If `$ARGUMENTS` contains `dry-run`: execute Phase 1's triage, print the planned execution order as a dependency-sorted list, and STOP.
|
||||
|
||||
## Phase 1 — Triage & Ordering
|
||||
|
||||
1. Run `bd ready` for actionable issues (respect `$ARGUMENTS` priority/epic filter if given).
|
||||
2. Run `bd blocked` and `bd show <id>` on each blocked issue to map the dependency graph.
|
||||
3. Run `bd orphans` — repair or flag any broken dependencies (`bd dep add` / `bd human <id>`).
|
||||
4. Build a topologically-sorted work queue: priority order (P0 → P4) within dependency order. Issues whose completion unblocks the most downstream work get tie-breaker preference.
|
||||
5. Run `bd lint` on the queue. For issues with missing/vague requirements, attempt to infer acceptance criteria from the description and codebase, update via `bd update <id> --acceptance="..."`. If requirements are genuinely undecidable, run `bd human <id>` with a specific question and skip it (do not guess on ambiguous product decisions).
|
||||
|
||||
## Phase 2 — The Drain Loop
|
||||
|
||||
Repeat until the exit condition in Phase 3 is met. For **each** issue in the queue:
|
||||
|
||||
### 2a. Claim
|
||||
```bash
|
||||
bd show <id> # re-read full details, dependencies, acceptance criteria
|
||||
bd update <id> --claim # mark in_progress
|
||||
```
|
||||
|
||||
### 2b. Implement
|
||||
- Read the acceptance criteria, design notes, and any linked issues before writing code.
|
||||
- Locate the relevant code with Glob/Grep; understand existing patterns before adding new ones.
|
||||
- Implement the minimal complete change that satisfies the requirements. Follow existing repo conventions.
|
||||
- If the issue is a `feature` without tests specified, write tests anyway — untested features do not count as done.
|
||||
- If during implementation you discover necessary sub-work, create it immediately: `bd create --title="..." --description="..." --type=task --priority=<match parent>` then `bd dep add <new-id> <current-id>` as appropriate. Never leave discovered work untracked.
|
||||
|
||||
### 2c. Verify (hard gates — ALL must pass)
|
||||
```bash
|
||||
<TEST_CMD> # full test suite, not just new tests
|
||||
<BUILD_CMD> # full build
|
||||
<LINT_CMD> # if present
|
||||
```
|
||||
- ✅ All tests pass (including pre-existing ones — no regressions)
|
||||
- ✅ Build succeeds cleanly
|
||||
- ✅ Every acceptance criterion on the issue is demonstrably met
|
||||
- ✅ No new warnings/lint errors introduced
|
||||
|
||||
On failure: fix and re-verify. After **3 failed fix attempts** on the same root cause, stop thrashing — record findings with `bd update <id> --notes="<what was tried, error output, hypothesis>"`, run `bd human <id>` if it needs a decision, revert the working tree to the last green state, and move to the next issue.
|
||||
|
||||
### 2d. Close & Checkpoint
|
||||
```bash
|
||||
bd close <id> --reason="<one-line summary of what was done>" --suggest-next
|
||||
bd remember "<any non-obvious insight learned: gotcha, pattern, decision>"
|
||||
git add <changed files>
|
||||
git commit -m "<type>(<scope>): <summary> (closes <id>)"
|
||||
```
|
||||
- Commit per issue, not in batches — each commit should be independently green.
|
||||
- `--suggest-next` output feeds Phase 2e.
|
||||
|
||||
### 2e. Re-plan
|
||||
- Newly unblocked issues from `--suggest-next` are inserted into the queue in priority order.
|
||||
- Every **5 closed issues**, re-run `bd ready` and `bd blocked` to catch drift (issues added by hooks, remote changes), and re-run the full test suite even if the last issue didn't touch shared code.
|
||||
|
||||
### Parallelism
|
||||
When the queue contains **independent** issues (no shared files, no dependency relation), dispatch up to 3 in parallel via the Task tool (subagents), each following 2a–2d in isolation. Serialize anything touching shared modules, migrations, or config. Merge subagent commits sequentially and re-run TEST_CMD after each merge.
|
||||
|
||||
## Phase 3 — Exit Conditions & Escalation
|
||||
|
||||
The loop terminates when **one** of these holds:
|
||||
|
||||
1. **Success**: `bd ready` is empty AND `bd blocked` is empty (within the `$ARGUMENTS` scope) AND the final full TEST_CMD + BUILD_CMD run is green.
|
||||
2. **Human-gated**: remaining issues are all flagged via `bd human` — report them with the specific decision needed for each.
|
||||
3. **Externally blocked**: remaining blockers depend on things outside this repo (third-party, credentials, other teams) — document each with `bd update <id> --notes` and report.
|
||||
|
||||
Never terminate by silently skipping issues. Every open issue at exit must be either human-flagged or externally blocked with notes explaining why.
|
||||
|
||||
## Phase 4 — Session Close Protocol (MANDATORY)
|
||||
|
||||
```bash
|
||||
[ ] git status # confirm nothing unstaged/untracked left behind
|
||||
[ ] git add <files> # stage any stragglers
|
||||
[ ] bd dolt pull # pull beads updates from main
|
||||
[ ] git commit -m "..." # final commit if anything staged
|
||||
[ ] bd stats # final counts
|
||||
```
|
||||
|
||||
Then produce the **Drain Report**:
|
||||
|
||||
- **Burn-down**: baseline vs final counts (open / in_progress / blocked / closed this session)
|
||||
- **Closed**: each issue ID + one-line summary + commit SHA
|
||||
- **Escalated**: each `bd human` flag with the exact decision needed
|
||||
- **Externally blocked**: each with the external dependency named
|
||||
- **Discovered work**: new issues created during the drain
|
||||
- **Insights recorded**: `bd remember` entries added
|
||||
- **Final verification**: test suite result, build result, lint result
|
||||
|
||||
## Hard Rules
|
||||
|
||||
- Use beads for ALL tracking. Never TodoWrite, TaskCreate, or markdown task files.
|
||||
- Never `bd edit` (blocks on $EDITOR).
|
||||
- Never close an issue whose acceptance criteria aren't verifiably met — a passing build is necessary, not sufficient.
|
||||
- Never commit with a red test suite.
|
||||
- Priority values are numeric (0–4 / P0–P4), never "high"/"medium"/"low".
|
||||
- Persistence you don't need beats lost context: over-record notes, insights, and reasons.
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
description: Extract insight-type learnings from claude-mem and record them into beads memories
|
||||
---
|
||||
|
||||
# Sync claude-mem insights → beads memories
|
||||
|
||||
<!--toc:start-->
|
||||
- [Sync claude-mem insights → beads memories](#sync-claude-mem-insights-beads-memories)
|
||||
- [Scope (read carefully)](#scope-read-carefully)
|
||||
- [Phase 0 — Preflight](#phase-0-preflight)
|
||||
- [Phase 1 — Enumerate ALL learnings (the loop)](#phase-1-enumerate-all-learnings-the-loop)
|
||||
- [Phase 2 — Triage & record (per-item loop)](#phase-2-triage-record-per-item-loop)
|
||||
- [Phase 3 — Finalize](#phase-3-finalize)
|
||||
- [Guardrails](#guardrails)
|
||||
<!--toc:end-->
|
||||
|
||||
You are migrating **durable insights** from **claude-mem** (the session memory store)
|
||||
into **beads** (`bd remember`) for this repository. Work autonomously through a loop
|
||||
until every relevant observation has been triaged. Do not invent learnings — only
|
||||
persist what claude-mem actually returns.
|
||||
|
||||
## Scope (read carefully)
|
||||
|
||||
- **Record ONLY insights / decisions / gotchas** → `bd remember`.
|
||||
- **Ignore actionable learnings** (bugs to fix, tech debt, follow-ups, TODOs).
|
||||
Do **not** create them as beads issues. A separate command will later pull those
|
||||
from claude-mem and feed them into **Linear** for PM; beads then syncs from Linear.
|
||||
- This command therefore **never calls `bd create`** and never writes beads issues.
|
||||
The only write to beads is `bd remember`. Leave actionable items untouched in
|
||||
claude-mem so the future Linear command can pick them up.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Preflight
|
||||
|
||||
1. Confirm beads is live in this repo: `bd ready` (and `bd doctor` if it errors).
|
||||
2. Snapshot existing memories for dedup: `bd memories ""` (plus a few broad keyword
|
||||
`bd memories <term>` lookups) and keep the gist in mind.
|
||||
3. Set up a **local progress file** for resumability (so compaction/re-runs skip done
|
||||
work) — NOT a beads issue:
|
||||
```
|
||||
./.claude-mem-sync/processed.json # { "processed": [<cmem ids>], "skipped_actionable": <count> }
|
||||
```
|
||||
Create it if missing; load it if present. Add `.claude-mem-sync/` to `.gitignore`
|
||||
if it isn't already.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Enumerate ALL learnings (the loop)
|
||||
|
||||
claude-mem search is query-based, so a single call won't surface everything. Build a
|
||||
**complete, de-duplicated set of observation IDs** by sweeping across angles, then
|
||||
walking chronologically. Track seen IDs in a set; never process the same ID twice.
|
||||
|
||||
Use `/claude-mem:mem-search` for every query below, following claude-mem's 3-layer
|
||||
pattern — pull the compact **index** first, only fetch full details for IDs you keep.
|
||||
|
||||
**1a. Type sweep** — one broad query per observation type, high limit:
|
||||
```
|
||||
/claude-mem:mem-search (type=insight)
|
||||
/claude-mem:mem-search (type=decision)
|
||||
/claude-mem:mem-search (type=bugfix) # scan for the *lesson learned*, not the fix-task
|
||||
/claude-mem:mem-search (type=architecture)
|
||||
/claude-mem:mem-search (type=feature) # plus any other types this project uses
|
||||
```
|
||||
> You still scan every type — a bugfix or feature observation often contains a durable
|
||||
> *insight* ("X breaks when Y") even though its actionable part is ignored here.
|
||||
|
||||
**1b. Topic sweep** — queries for the repo's recurring themes (infer from the codebase:
|
||||
auth, deploy, config, performance, gotchas, "why we", "decided", "learned", "don't").
|
||||
Each adds new IDs to the set.
|
||||
|
||||
**1c. Chronological walk** — to catch what the sweeps missed, seed `timeline` from your
|
||||
earliest and latest known observations and step through history, collecting any IDs not
|
||||
already in the set. Stop when the timeline yields no new IDs in either direction.
|
||||
|
||||
Result: a deduplicated list of candidate observation IDs. Print the count.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Triage & record (per-item loop)
|
||||
|
||||
Process candidate IDs in batches. For each batch:
|
||||
|
||||
1. **Fetch details** once: `get_observations(ids=[...])` (batch IDs — never one-at-a-time).
|
||||
2. For **each** observation, classify:
|
||||
|
||||
- **Actionable** (a thing to *do*: unfixed bug, tech debt, follow-up, TODO) →
|
||||
**IGNORE**. Increment `skipped_actionable` in the progress file and move on.
|
||||
It stays in claude-mem for the Linear command.
|
||||
|
||||
- **Insight / decision / gotcha** (durable knowledge about *how things are*) →
|
||||
record it:
|
||||
- **Dedup check** first: `bd memories <key terms>`. If beads already captures it, skip.
|
||||
- Then:
|
||||
```
|
||||
bd remember "<one-line durable insight, self-contained, no session context> [cmem #<id>]"
|
||||
```
|
||||
Keep it atomic and reusable. Include the source `cmem #<id>` so it traces back
|
||||
to http://localhost:37777/api/observation/<id>.
|
||||
|
||||
- **Noise** (one-off output, ephemeral state, trivially obvious, duplicate) → skip silently.
|
||||
|
||||
3. Append processed IDs to `./.claude-mem-sync/processed.json`.
|
||||
|
||||
Repeat until the candidate set is exhausted.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Finalize
|
||||
|
||||
1. Sanity pass: `bd memories ""` — confirm new insights landed and read cleanly.
|
||||
2. Sync beads memories to remote: `bd dolt push`.
|
||||
3. **Session close protocol** — if any code/files changed (e.g. `.gitignore`):
|
||||
```
|
||||
git status
|
||||
git add <files>
|
||||
git commit -m "chore: record claude-mem insights into beads"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Insights only.** Never `bd create`, never write a beads issue. Actionable items are
|
||||
ignored and left in claude-mem for the Linear sync command.
|
||||
- **Idempotent.** Re-running must not duplicate — always dedup against `bd memories` and
|
||||
the local progress file before writing.
|
||||
- **Atomic memories.** One insight per `bd remember`, self-contained, no "in this session"
|
||||
phrasing.
|
||||
- **Cite the source.** Every entry carries its `cmem #<id>` for traceability.
|
||||
- **No `bd edit`** — it opens an editor and blocks.
|
||||
- **Don't fabricate** — if a sweep returns nothing, say so and move on.
|
||||
- For large sets, run the type/topic sweeps and `bd memories` dedup lookups with
|
||||
**parallel subagents** for speed.
|
||||
|
||||
When done, report: total observations scanned, how many insights were recorded, how many
|
||||
were skipped as **actionable** (this is the backlog the Linear command will handle), and
|
||||
how many were skipped as noise/duplicates.
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
description: Extract actionable learnings from claude-mem into beads tasks and push them up to Linear for PM
|
||||
---
|
||||
|
||||
# Sync claude-mem actionable learnings → beads → Linear
|
||||
|
||||
<!--toc:start-->
|
||||
- [Sync claude-mem actionable learnings → beads → Linear](#sync-claude-mem-actionable-learnings-beads-linear)
|
||||
- [Scope (read carefully)](#scope-read-carefully)
|
||||
- [Sync model (no linear-cli needed)](#sync-model-no-linear-cli-needed)
|
||||
- [Phase 0 — Preflight](#phase-0-preflight)
|
||||
- [Phase 1 — Enumerate ALL learnings (the loop)](#phase-1-enumerate-all-learnings-the-loop)
|
||||
- [Phase 2 — Triage & create (per-item loop)](#phase-2-triage-create-per-item-loop)
|
||||
- [Phase 3 — Push to Linear](#phase-3-push-to-linear)
|
||||
- [Phase 4 — Finalize](#phase-4-finalize)
|
||||
- [Guardrails](#guardrails)
|
||||
<!--toc:end-->
|
||||
|
||||
You are turning **actionable learnings** from **claude-mem** (the session memory store)
|
||||
into **beads** (`bd`) tasks, then pushing the new ones up to **Linear** for PM. Work
|
||||
autonomously through a loop until every relevant observation has been triaged. Do not
|
||||
invent learnings — only persist what claude-mem actually returns.
|
||||
|
||||
## Scope (read carefully)
|
||||
|
||||
- **Record ONLY actionable learnings** — things to *do*: unfixed bugs, tech debt,
|
||||
follow-ups, TODOs, missing tests, planned refactors. Each becomes a `bd create` task.
|
||||
- **Ignore insights / decisions / gotchas** (durable knowledge about *how things are*).
|
||||
A separate command records those as `bd remember` memories — do **not** touch them here.
|
||||
Leave them in claude-mem untouched.
|
||||
- A single observation may legitimately contain both an insight *and* an action item; the
|
||||
two commands are independent, so it's fine if this one creates a task while the other
|
||||
records a memory from the same `cmem #<id>`.
|
||||
|
||||
## Sync model (no linear-cli needed)
|
||||
|
||||
Beads-first, push up, bidirectional thereafter:
|
||||
1. Create tasks in beads (`bd create`).
|
||||
2. Push the new ones to Linear with `bd linear push <ids>` — this creates the Linear
|
||||
issues and writes `external_ref` back onto each bead (`--update-refs` is default true).
|
||||
3. From then on, `bd linear sync` is bidirectional: PM edits in Linear pull back into beads.
|
||||
|
||||
`linear-cli` is **not** used. All Linear interaction goes through native `bd linear`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Preflight
|
||||
|
||||
1. Confirm beads is live: `bd ready` (and `bd doctor` if it errors).
|
||||
2. Confirm Linear is wired up: `bd linear status`. If it errors / unconfigured, stop and
|
||||
tell the user to set `linear.api_key` + team (`bd linear teams` to find the team UUID).
|
||||
Note whether **multiple teams** are configured (`linear.team_ids`) — if so, push needs
|
||||
an explicit `--team <ID>`; ask the user which team these tasks belong to.
|
||||
3. Dedup snapshot: `bd list --status=open` and a few `bd search <term>` lookups so you can
|
||||
recognize existing tasks (including ones already pulled from Linear).
|
||||
4. Local progress file for resumability — NOT a beads issue:
|
||||
```
|
||||
./.claude-mem-sync/processed-actions.json # { "processed": [<cmem ids>], "created": [<bead ids>], "skipped_insights": <n> }
|
||||
```
|
||||
Create if missing, load if present. Ensure `.claude-mem-sync/` is in `.gitignore`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Enumerate ALL learnings (the loop)
|
||||
|
||||
claude-mem search is query-based, so one call won't surface everything. Build a
|
||||
**complete, de-duplicated set of observation IDs** by sweeping across angles, then walking
|
||||
chronologically. Track seen IDs in a set; never process the same ID twice.
|
||||
|
||||
Use `/claude-mem:mem-search` for every query below, following claude-mem's 3-layer pattern
|
||||
— pull the compact **index** first, only fetch full details for IDs you keep.
|
||||
|
||||
**1a. Type sweep** — one broad query per observation type, high limit:
|
||||
```
|
||||
/claude-mem:mem-search (type=bugfix)
|
||||
/claude-mem:mem-search (type=feature)
|
||||
/claude-mem:mem-search (type=insight) # scan for the *action item* buried inside, not the insight
|
||||
/claude-mem:mem-search (type=decision)
|
||||
/claude-mem:mem-search (type=architecture) # plus any other types this project uses
|
||||
```
|
||||
> Scan every type — even an `insight` observation often ends with "…so we should do X",
|
||||
> which is the action item you extract here while ignoring the insight itself.
|
||||
|
||||
**1b. Topic sweep** — queries for action-shaped language the codebase tends to record:
|
||||
"TODO", "should", "need to", "fix", "broken", "flaky", "refactor", "tech debt", "later",
|
||||
"workaround", "temporary", "follow up". Each adds new IDs to the set.
|
||||
|
||||
**1c. Chronological walk** — seed `timeline` from your earliest and latest known
|
||||
observations and step through history, collecting any IDs not already in the set. Stop when
|
||||
the timeline yields no new IDs in either direction.
|
||||
|
||||
Result: a deduplicated list of candidate observation IDs. Print the count.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Triage & create (per-item loop)
|
||||
|
||||
Process candidate IDs in batches. For each batch:
|
||||
|
||||
1. **Fetch details** once: `get_observations(ids=[...])` (batch IDs — never one-at-a-time).
|
||||
2. For **each** observation, classify:
|
||||
|
||||
- **Insight / decision / gotcha** (knowledge, nothing to *do*) → **IGNORE**. Increment
|
||||
`skipped_insights` and move on. It's the other command's job.
|
||||
|
||||
- **Noise** (one-off output, ephemeral state, trivially obvious, duplicate) → skip silently.
|
||||
|
||||
- **Actionable** → create a task:
|
||||
- **Dedup first:** `bd search "<key terms>"` and `bd search "cmem #<id>"`. If a matching
|
||||
task already exists (locally or pulled from Linear), skip — this keeps re-runs idempotent.
|
||||
- Then:
|
||||
```
|
||||
bd create --title="<imperative summary>" \
|
||||
--description="<what + why, ending with: Source: cmem #<id>>" \
|
||||
--type=bug|task|feature \
|
||||
--priority=<0-4>
|
||||
```
|
||||
- Priority is `0-4` / `P0-P4` (0=critical … 4=backlog) — never high/medium/low.
|
||||
bd maps this to Linear priority on push.
|
||||
- Optionally add `--acceptance="<done criteria>"` when the observation implies one.
|
||||
- If two items depend on each other: `bd dep add <issue> <depends-on>`.
|
||||
- Record the new bead id and the `cmem #<id>` in the progress file.
|
||||
|
||||
Repeat until the candidate set is exhausted.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Push to Linear
|
||||
|
||||
1. Review what's queued: `bd linear status` (shows issues pending push, i.e. no external_ref).
|
||||
2. Push **only the tasks you just created**, by id, so you don't drag along unrelated pending work:
|
||||
```
|
||||
bd linear push <new-bead-id-1> <new-bead-id-2> ...
|
||||
```
|
||||
- Add `--team <ID>` if multiple teams are configured (from Phase 0).
|
||||
- Run `--dry-run` first if the user wants a preview.
|
||||
- This creates the Linear issues and sets `external_ref` on each bead (default `--update-refs`).
|
||||
- Alternative for bulk: `bd linear sync --push --create-only` (+ `--team`), but prefer the
|
||||
explicit id list for precision.
|
||||
3. Confirm linkage: re-run `bd linear status` and spot-check a couple of beads now carry an
|
||||
`external_ref` to Linear.
|
||||
|
||||
> Steady state: after this seeding push, a scheduled or manual `bd linear sync` keeps both
|
||||
> sides aligned — PM's changes in Linear pull back down to beads. You don't push again for
|
||||
> these; you only push *newly created* tasks on future runs.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Finalize
|
||||
|
||||
1. Sync beads to its Dolt remote: `bd dolt push`.
|
||||
2. **Session close protocol** — if any code/files changed (e.g. `.gitignore`):
|
||||
```
|
||||
git status
|
||||
git add <files>
|
||||
git commit -m "chore: extract claude-mem action items into beads + Linear"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **Actionable only.** Never `bd remember` here. Insights are ignored and left in claude-mem
|
||||
for the insights command.
|
||||
- **No linear-cli.** All Linear interaction is native `bd linear`.
|
||||
- **Idempotent.** Re-running must not duplicate — dedup against `bd search` (including
|
||||
`bd search "cmem #<id>"`) and the progress file before creating, and push only new ids.
|
||||
- **Cite the source.** Every task description ends with `Source: cmem #<id>`
|
||||
(traceable at http://localhost:37777/api/observation/<id>).
|
||||
- **No `bd edit`** — it opens an editor and blocks. Use inline `--` flags on create/update.
|
||||
- **Multiple teams → explicit `--team`** on push; ask the user if ambiguous.
|
||||
- **Don't fabricate** — if a sweep returns nothing, say so and move on.
|
||||
- For large sets, run the type/topic sweeps and `bd search` dedup lookups with **parallel
|
||||
subagents** for speed (but run `bd create` / `bd linear push` serially to keep ids ordered).
|
||||
|
||||
When done, report: total observations scanned, how many tasks were created (with bead ids),
|
||||
how many pushed to Linear (with external_refs), how many skipped as **insights** (the other
|
||||
command's backlog), and how many skipped as noise/duplicates.
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
description: Plan a task by decomposing it into beads issues with dependencies, acceptance criteria, and priorities
|
||||
argument-hint: <task description or goal>
|
||||
allowed-tools: Bash(bd:*), Bash(git log:*), Bash(git status:*), Bash(rg:*), Task
|
||||
---
|
||||
|
||||
# /create-task — Plan work into beads
|
||||
|
||||
<!--toc:start-->
|
||||
- [/create-task — Plan work into beads](#create-task-plan-work-into-beads)
|
||||
- [Current workspace state](#current-workspace-state)
|
||||
- [Task to plan](#task-to-plan)
|
||||
- [Instructions](#instructions)
|
||||
- [1. Understand before creating](#1-understand-before-creating)
|
||||
- [2. Decompose](#2-decompose)
|
||||
- [3. Create issues](#3-create-issues)
|
||||
- [4. Wire dependencies](#4-wire-dependencies)
|
||||
- [5. Report the plan](#5-report-the-plan)
|
||||
<!--toc:end-->
|
||||
|
||||
## Current workspace state
|
||||
|
||||
- Ready work: !`bd ready 2>/dev/null | head -30`
|
||||
- In progress: !`bd list --status=in_progress 2>/dev/null | head -15`
|
||||
- Recently closed (dedup check): !`bd list --status=closed 2>/dev/null | head -10`
|
||||
- Stats: !`bd stats 2>/dev/null`
|
||||
- Relevant memories: !`bd memories "$ARGUMENTS" 2>/dev/null | head -40`
|
||||
|
||||
## Task to plan
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Instructions
|
||||
|
||||
You are planning this task using **beads as the sole tracker**. Do NOT use TodoWrite, TaskCreate, or markdown checklists. Do NOT write any code in this command — output is a set of beads issues forming an executable plan.
|
||||
|
||||
### 1. Understand before creating
|
||||
|
||||
- Search for prior art first: `bd search "<keywords>"` — the task (or part of it) may already exist. Per repo convention, `contracts-*`/`backend-*`/`core-*` beads mirror Linear CORE-* and share ID suffixes across sibling repos; if something looks missing, check sibling repo beads and `git log` before assuming it needs a new issue.
|
||||
- Check the injected memories above for constraints, gotchas, and prior decisions that shape the plan (e.g., root-file serialization, generated-file rules, runtime conventions).
|
||||
- If the request is ambiguous on scope, ask ONE clarifying question, then proceed.
|
||||
|
||||
### 2. Decompose
|
||||
|
||||
Break the task into issues sized for a single focused session (roughly ≤ half a day each). For each issue decide:
|
||||
|
||||
- **type**: `feature` (new capability), `task` (chore/refactor/infra), `bug` (defect)
|
||||
- **priority**: numeric only — `0` critical / `1` high / `2` medium / `3` low / `4` backlog. Never "high"/"medium"/"low".
|
||||
- **description**: WHY the issue exists + WHAT done looks like. Never a bare title restatement.
|
||||
- **acceptance criteria**: concrete, verifiable (tests pass, command output, deployed address updated, etc.)
|
||||
- **design** (when a decision was made): record it so future sessions don't re-litigate.
|
||||
|
||||
If the plan touches shared root files (`turbo.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, root Biome/tsconfig), note it in the issue and **serialize those issues with dependencies** — they cannot run in parallel.
|
||||
|
||||
### 3. Create issues
|
||||
|
||||
Use the full quality flags:
|
||||
|
||||
```bash
|
||||
bd create \
|
||||
--title="<imperative summary>" \
|
||||
--description="<why + what>" \
|
||||
--type=<task|bug|feature> \
|
||||
--priority=<0-4> \
|
||||
--acceptance="<verifiable criteria>" \
|
||||
--design="<decisions, if any>" \
|
||||
--notes="<gotchas from memories, file paths, related beads/Linear IDs>" \
|
||||
--validate
|
||||
```
|
||||
|
||||
- **3+ issues → spawn parallel subagents**, one `bd create` batch each, then collect the returned IDs.
|
||||
- Quote every string flag (descriptions contain `&`, `$`, backticks).
|
||||
- NEVER use `bd edit` (opens $EDITOR and blocks). Amend with `bd update <id> --description/--notes/--design`.
|
||||
|
||||
### 4. Wire dependencies
|
||||
|
||||
```bash
|
||||
bd dep add <dependent> <blocker> # dependent depends on blocker
|
||||
```
|
||||
|
||||
- Model the real execution order: tests depend on implementation, redeploys depend on ABI changes, root-file edits form a chain.
|
||||
- Verify with `bd blocked` and `bd show <id>` that the graph matches intent — no cycles, no orphans (`bd orphans`).
|
||||
|
||||
### 5. Report the plan
|
||||
|
||||
Output a concise summary:
|
||||
|
||||
1. **Created issues** — table of `id | title | type | priority`
|
||||
2. **Dependency graph** — short text sketch of the ordering (e.g. `x8y → oto → 53x`)
|
||||
3. **Entry point** — which issue(s) show in `bd ready` right now, i.e., where work starts
|
||||
4. **Deferred/skipped** — anything that already existed (with the existing ID) or was intentionally left out
|
||||
|
||||
Then persist and finish:
|
||||
|
||||
```bash
|
||||
bd ready # confirm entry points are unblocked
|
||||
git status # beads auto-commits to Dolt; push if session ends here
|
||||
```
|
||||
|
||||
If planning surfaced a durable insight (a constraint, a decision, a gotcha), store it: `bd remember "<insight>"` — never a MEMORY.md file.
|
||||
|
||||
Do NOT start implementing any issue. Planning ends when the graph is created, validated, and reported. Implementation begins in a later session via `bd ready` → `bd update <id> --claim`.
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
description: Run accessibility and visual design review
|
||||
---
|
||||
|
||||
# Rams Design Review
|
||||
|
||||
You are Rams, an expert design engineer reviewing code for accessibility and visual design issues.
|
||||
|
||||
## Mode
|
||||
|
||||
If `$ARGUMENTS` is provided, analyze that specific file.
|
||||
If `$ARGUMENTS` is empty, ask the user which file(s) to review, or offer to scan the project for component files.
|
||||
|
||||
---
|
||||
|
||||
## 1. Accessibility Review (WCAG 2.1)
|
||||
|
||||
### Critical (Must Fix)
|
||||
|
||||
| Check | WCAG | What to look for |
|
||||
|-------|------|------------------|
|
||||
| Images without alt | 1.1.1 | `<img>` without `alt` attribute |
|
||||
| Icon-only buttons | 4.1.2 | `<button>` with only SVG/icon, no `aria-label` |
|
||||
| Form inputs without labels | 1.3.1 | `<input>`, `<select>`, `<textarea>` without associated `<label>` or `aria-label` |
|
||||
| Non-semantic click handlers | 2.1.1 | `<div onClick>` or `<span onClick>` without `role`, `tabIndex`, `onKeyDown` |
|
||||
| Missing link destination | 2.1.1 | `<a>` without `href` using only `onClick` |
|
||||
|
||||
### Serious (Should Fix)
|
||||
|
||||
| Check | WCAG | What to look for |
|
||||
|-------|------|------------------|
|
||||
| Focus outline removed | 2.4.7 | `outline-none` or `outline: none` without visible focus replacement |
|
||||
| Missing keyboard handlers | 2.1.1 | Interactive elements with `onClick` but no `onKeyDown`/`onKeyUp` |
|
||||
| Color-only information | 1.4.1 | Status/error indicated only by color (no icon/text) |
|
||||
| Touch target too small | 2.5.5 | Clickable elements smaller than 44x44px |
|
||||
|
||||
### Moderate (Consider Fixing)
|
||||
|
||||
| Check | WCAG | What to look for |
|
||||
|-------|------|------------------|
|
||||
| Heading hierarchy | 1.3.1 | Skipped heading levels (h1 → h3) |
|
||||
| Positive tabIndex | 2.4.3 | `tabIndex` > 0 (disrupts natural tab order) |
|
||||
| Role without required attributes | 4.1.2 | `role="button"` without `tabIndex="0"` |
|
||||
|
||||
---
|
||||
|
||||
## 2. Visual Design Review
|
||||
|
||||
### Layout & Spacing
|
||||
- Inconsistent spacing values
|
||||
- Overflow issues, alignment problems
|
||||
- Z-index conflicts
|
||||
|
||||
### Typography
|
||||
- Mixed font families, weights, or sizes
|
||||
- Line height issues
|
||||
- Missing font fallbacks
|
||||
|
||||
### Color & Contrast
|
||||
- Contrast ratio below 4.5:1
|
||||
- Missing hover/focus states
|
||||
- Dark mode inconsistencies
|
||||
|
||||
### Components
|
||||
- Missing button states (disabled, loading, hover, active, focus)
|
||||
- Missing form field states (error, success, disabled)
|
||||
- Inconsistent borders, shadows, or icon sizing
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
═══════════════════════════════════════════════════
|
||||
RAMS DESIGN REVIEW: [filename]
|
||||
═══════════════════════════════════════════════════
|
||||
|
||||
CRITICAL (X issues)
|
||||
───────────────────
|
||||
[A11Y] Line 24: Button missing accessible name
|
||||
<button><CloseIcon /></button>
|
||||
Fix: Add aria-label="Close"
|
||||
WCAG: 4.1.2
|
||||
|
||||
SERIOUS (X issues)
|
||||
──────────────────
|
||||
...
|
||||
|
||||
═══════════════════════════════════════════════════
|
||||
SUMMARY: X critical, X serious, X moderate
|
||||
Score: XX/100
|
||||
═══════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
1. Read the file(s) first before making assessments
|
||||
2. Be specific with line numbers and code snippets
|
||||
3. Provide fixes, not just problems
|
||||
4. Prioritize critical accessibility issues first
|
||||
|
||||
If asked, offer to fix the issues directly.
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
description: Review UI code for Vercel Web Interface Guidelines compliance
|
||||
argument-hint: <file-or-pattern>
|
||||
---
|
||||
|
||||
# Web Interface Guidelines
|
||||
|
||||
Review these files for compliance: $ARGUMENTS
|
||||
|
||||
Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
|
||||
|
||||
## Rules
|
||||
|
||||
### Accessibility
|
||||
|
||||
- Icon-only buttons need `aria-label`
|
||||
- Form controls need `<label>` or `aria-label`
|
||||
- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
|
||||
- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
|
||||
- Images need `alt` (or `alt=""` if decorative)
|
||||
- Decorative icons need `aria-hidden="true"`
|
||||
- Async updates (toasts, validation) need `aria-live="polite"`
|
||||
- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
|
||||
- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
|
||||
- `scroll-margin-top` on heading anchors
|
||||
|
||||
### Focus States
|
||||
|
||||
- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
|
||||
- Never `outline-none` / `outline: none` without focus replacement
|
||||
- Use `:focus-visible` over `:focus` (avoid focus ring on click)
|
||||
- Group focus with `:focus-within` for compound controls
|
||||
|
||||
### Forms
|
||||
|
||||
- Inputs need `autocomplete` and meaningful `name`
|
||||
- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
|
||||
- Never block paste (`onPaste` + `preventDefault`)
|
||||
- Labels clickable (`htmlFor` or wrapping control)
|
||||
- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
|
||||
- Checkboxes/radios: label + control share single hit target (no dead zones)
|
||||
- Submit button stays enabled until request starts; spinner during request
|
||||
- Errors inline next to fields; focus first error on submit
|
||||
- Placeholders end with `…` and show example pattern
|
||||
- `autocomplete="off"` on non-auth fields to avoid password manager triggers
|
||||
- Warn before navigation with unsaved changes (`beforeunload` or router guard)
|
||||
|
||||
### Animation
|
||||
|
||||
- Honor `prefers-reduced-motion` (provide reduced variant or disable)
|
||||
- Animate `transform`/`opacity` only (compositor-friendly)
|
||||
- Never `transition: all`—list properties explicitly
|
||||
- Set correct `transform-origin`
|
||||
- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
|
||||
- Animations interruptible—respond to user input mid-animation
|
||||
|
||||
### Typography
|
||||
|
||||
- `…` not `...`
|
||||
- Curly quotes `"` `"` not straight `"`
|
||||
- Non-breaking spaces: `10 MB`, `⌘ K`, brand names
|
||||
- Loading states end with `…`: `"Loading…"`, `"Saving…"`
|
||||
- `font-variant-numeric: tabular-nums` for number columns/comparisons
|
||||
- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
|
||||
|
||||
### Content Handling
|
||||
|
||||
- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
|
||||
- Flex children need `min-w-0` to allow text truncation
|
||||
- Handle empty states—don't render broken UI for empty strings/arrays
|
||||
- User-generated content: anticipate short, average, and very long inputs
|
||||
|
||||
### Images
|
||||
|
||||
- `<img>` needs explicit `width` and `height` (prevents CLS)
|
||||
- Below-fold images: `loading="lazy"`
|
||||
- Above-fold critical images: `priority` or `fetchpriority="high"`
|
||||
|
||||
### Performance
|
||||
|
||||
- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
|
||||
- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
|
||||
- Batch DOM reads/writes; avoid interleaving
|
||||
- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
|
||||
- Add `<link rel="preconnect">` for CDN/asset domains
|
||||
- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
|
||||
|
||||
### Navigation & State
|
||||
|
||||
- URL reflects state—filters, tabs, pagination, expanded panels in query params
|
||||
- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
|
||||
- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
|
||||
- Destructive actions need confirmation modal or undo window—never immediate
|
||||
|
||||
### Touch & Interaction
|
||||
|
||||
- `touch-action: manipulation` (prevents double-tap zoom delay)
|
||||
- `-webkit-tap-highlight-color` set intentionally
|
||||
- `overscroll-behavior: contain` in modals/drawers/sheets
|
||||
- During drag: disable text selection, `inert` on dragged elements
|
||||
- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
|
||||
|
||||
### Safe Areas & Layout
|
||||
|
||||
- Full-bleed layouts need `env(safe-area-inset-*)` for notches
|
||||
- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
|
||||
- Flex/grid over JS measurement for layout
|
||||
|
||||
### Dark Mode & Theming
|
||||
|
||||
- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
|
||||
- `<meta name="theme-color">` matches page background
|
||||
- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
|
||||
|
||||
### Locale & i18n
|
||||
|
||||
- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
|
||||
- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
|
||||
- Detect language via `Accept-Language` / `navigator.languages`, not IP
|
||||
- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
|
||||
|
||||
### Hydration Safety
|
||||
|
||||
- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
|
||||
- Date/time rendering: guard against hydration mismatch (server vs client)
|
||||
- `suppressHydrationWarning` only where truly needed
|
||||
|
||||
### Hover & Interactive States
|
||||
|
||||
- Buttons/links need `hover:` state (visual feedback)
|
||||
- Interactive states increase contrast: hover/active/focus more prominent than rest
|
||||
|
||||
### Content & Copy
|
||||
|
||||
- Active voice: "Install the CLI" not "The CLI will be installed"
|
||||
- Title Case for headings/buttons (Chicago style)
|
||||
- Numerals for counts: "8 deployments" not "eight"
|
||||
- Specific button labels: "Save API Key" not "Continue"
|
||||
- Error messages include fix/next step, not just problem
|
||||
- Second person; avoid first person
|
||||
- `&` over "and" where space-constrained
|
||||
|
||||
### Anti-patterns (flag these)
|
||||
|
||||
- `user-scalable=no` or `maximum-scale=1` disabling zoom
|
||||
- `onPaste` with `preventDefault`
|
||||
- `transition: all`
|
||||
- `outline-none` without focus-visible replacement
|
||||
- Inline `onClick` navigation without `<a>`
|
||||
- `<div>` or `<span>` with click handlers (should be `<button>`)
|
||||
- Images without dimensions
|
||||
- Large arrays `.map()` without virtualization
|
||||
- Form inputs without labels
|
||||
- Icon buttons without `aria-label`
|
||||
- Hardcoded date/number formats (use `Intl.*`)
|
||||
- `autoFocus` without clear justification
|
||||
|
||||
## Output Format
|
||||
|
||||
Group by file. Use `file:line` format (VS Code clickable). Terse findings.
|
||||
|
||||
```text
|
||||
## src/Button.tsx
|
||||
|
||||
src/Button.tsx:42 - icon button missing aria-label
|
||||
src/Button.tsx:18 - input lacks label
|
||||
src/Button.tsx:55 - animation missing prefers-reduced-motion
|
||||
src/Button.tsx:67 - transition: all → list properties
|
||||
|
||||
## src/Modal.tsx
|
||||
|
||||
src/Modal.tsx:12 - missing overscroll-behavior: contain
|
||||
src/Modal.tsx:34 - "..." → "…"
|
||||
|
||||
## src/Card.tsx
|
||||
|
||||
✓ pass
|
||||
```
|
||||
|
||||
State issue + location. Skip explanation unless fix non-obvious. No preamble.
|
||||
Reference in new issue
Block a user