Good afternoon, Alex Chen β¨
Tue 27 Oct Β· here's where everything stands.
2/3today
planned
1carried over
oldest from Mon 26
1due, not planned
due today
1/6this week
3 goals
4milestones
1 slipped
5waiting on you
pulled 13:13
Today
2- The reconciliation report is signed off (pf-101)
- The load-test plan is agreed with SRE (pf-104)
- 1Billing dual-write reconciliation report (cutover go/no-go)
- 2Quarterly access reviews (SOC 2 evidence)
Carried over Β· 1
- β»Fix timezone rounding in the legacy billing exporter
Due, not planned Β· 1
- !Send the board the activation funnel numbers
Roadmap
4- !M1Billing shadow modeβ³ Legacy exporter rounding fix (pf-099)
- βM2Launch gateβ³ Reconciliation report and go/no-go (pf-101)
- βM3SOC 2 evidenceβ³ Quarterly access reviews (cp-031)
- βM4Public status page
This week
2- platform: Ship the reconciliation report (pf-101) β go/no-go signed off
- platform: Run the 5x load test (pf-104) β p99 under 300 ms at peak
- growth: Empty-state redesign (gr-012) β variant B live to 50%
1 of 6 done
- Β·v2 load test at 5x peak (launch gate)
- Β·Empty-state redesign (activation step-2 leak)
- βDual-write shadow mode for usage billing
This month Β· October
1- v2 launched with zero Sev-1s in week one
- Usage-based billing cutover, reconciliation-gated
- Weekly active workspaces 1,840 to 2,100
1 of 7 done
- Β·Vendor inventory and DPA sweep
Queue
5My pull requests Β· 3
- #482 Reconciliation report: per-tenant drift table
- #479 Load-test harness at 5x peak
- #471 Exporter timezone rounding
Reviews I owe Β· 2
Later
1
Later
1- Β·Push-notification opt-in experiment
Not planned
1
Not planned
1- Β·Mobile 3.2 App Store review and release
π¬ Sessions Β· 3
15m agoBilling reconciliation walk
Waiting on the exporter fix
yesterdayLoad-test target
next: run the load test on Thursday
2 days agoSOC 2 evidence sprint
Access reviews 4 and 5
βοΈ Tasks touched Β· 6
β‘ Commands Β· 2
13:13/agent-kevin:sync
22 turns
βyesterday/agent-kevin:briefing evening
11 turns
π° Output Β· 6
Goalsfrom projects/TASKS.md
βοΈToday
- The reconciliation report is signed off (pf-101)
- The load-test plan is agreed with SRE (pf-104)
πWeekly
- platform: Ship the reconciliation report (pf-101) β go/no-go signed off
- platform: Run the 5x load test (pf-104) β p99 under 300 ms at peak
- growth: Empty-state redesign (gr-012) β variant B live to 50%
π―Monthly
- v2 launched with zero Sev-1s in week one
- Usage-based billing cutover, reconciliation-gated
- Weekly active workspaces 1,840 to 2,100
π§Yearly
- Q3 β v2 launch, billing migration, and clean SOC 2 Type II fieldwork
- Q4 β 2,500 weekly active workspaces; two senior platform engineers hired
Tasks
9 open tasks across 4 projects, by deadline.
0overdue
none
1due today
4due this week
2 in flight
3in flight
2blocked
1going stale
no update in 7d
βΆ In flight Β· 3
pf-101Billing dual-write reconciliation report (cutover go/no-go)platform㪠1P0
cp-031Quarterly access reviews (SOC 2 evidence)compliance㪠1P1
gr-012Empty-state redesign (activation step-2 leak)growth㪠1P1
π Due today Β· 1
gr-014Send the board the activation funnel numbersgrowth㪠1P1
π Due this week Β· 2
pf-104v2 load test at 5x peak (launch gate)platform㪠1P0
mb-032Mobile 3.2 App Store review and releasemobile㪠1P1
blocked bySubmitted; waiting on Apple review (typically 2 to 4 days).
π Due this month Β· 1
cp-028Vendor inventory and DPA sweepcompliance㪠1P2
βΎ No due date Β· 2
pf-099Fix timezone rounding in the legacy billing exporterplatform㪠1P1
mb-034Push-notification opt-in experimentmobile㪠1P2
blocked byNeeds 3.2 live (mb-032).
Projects
4 projects β click one to see its tasks.
4projects
4 with live tasks
4moving
updated in 7 days
1with blockers
a blocked task
0quiet
no live tasks
18%done overall
2 of 11 tasks
platform1 active Β· 2 open
Core API, billing, and infrastructure. Owns the v2 launch and the usage-based billing migration.
β 1 / 425%
25%
compliance1 active Β· 1 open
SOC 2 Type II track. Audit fieldwork starts in four weeks.
β 0 / 20%
0%
growth1 active Β· 1 open
Activation funnel, onboarding, and SEO. North star: weekly active workspaces.
β 1 / 333%
33%
mobile2 blocked
iOS and Android shipping app (React Native). 3.2 is in App Store review.
β 0 / 20%
0%
Sessions
What you and Ace worked on, captured automatically.
4sessions today
9last 7 days
none resumed
3on the radar
as of 13:15
Volumelast 7 days
Wed 597 BThu 407 BFri 692 BSat 502 BSun 230 BMon 261 BTue 481 B
Latest radar2026-10-27 13:15 Β· open
Launch-week prep across three threads: billing reconciliation, the load-test harness, and SOC 2 evidence.
π’ In motion (last hour)
1. Billing reconciliation walk Β· 15m ago
β Week-1 dual-write numbers reviewed (41 mismatches counted)
β Exporter's timezone rounding explains all 41 (filed as pf-099)
βΆ Waiting on the exporter fix
β· next: rerun the week-1 comparison once pf-099 lands
π Earlier
2. Load-test target Β· yesterday
β Settled 5x over 10x (agreed in the thread)
β Staging booked for Thursday (calendar invite sent)
β· next: run the load test on Thursday
3. SOC 2 evidence sprint Β· 2 days ago
β Access reviews 3 of 5 done (signed off)
β Okta checklist drafted (assumed)
βΆ Access reviews 4 and 5
β· next: chase the two remaining reviewers
3 sessions Β· 24h window Β· scoped to ~/agent-acme
2026-10-27
27 turns
build the empty-state variant behind a flag; the design link is in gr-012
9 turns
prep interview debrief notes for the two platform onsites and compile them into the hiring doc
35 turns
fix the exporter timezone rounding and replay the 41 mismatched invoices as a regression test
14 turns
draft the okta access review from the export and flag anything stale
2026-10-26
19 turns
should the load test target 10x or 5x peak
42 turns
reconciliation dashboard: match rate by day and a drilldown into mismatches
15 turns
confirm the funnel numbers on production before we brief the board
2026-10-25
31 turns
soc2 evidence sprint: pull the access lists and draft the review docs
24 turns
walk the 3.2 release checklist with me before we submit
Brain
Ace's living memory of your world β compiled from every session.
0pending compile
last compiled 30m ago
1inbox items
waiting to compile
1lint issues
0 errors Β· 1 warnings
4concepts
3 learnings
5active threads
Context loaded every session8 sources Β· 39.6 KB
instructions 32.2 KBidentity 2.2 KBknowledge 2.7 KBtasks 2.4 KB
| source | size | |
|---|---|---|
| β | .claude/CLAUDE.md project | 2.3 KB |
| β | AGENTS.md | 29.9 KB |
| β | SOUL.md | 718 B |
| β | IDENTITY.md | 1.0 KB |
| β | USER.md | 501 B |
| β | knowledge/index.mdThe master catalog β a table of contents for the whole knowledge base. It lists every permanent article with a one-line description, so Ace can find and load just what it needs on demand instead of pulling the entire brain into context every session. | 752 B |
| β | knowledge/memory/index.mdAceβs long-term memory: active threads, recent decisions, learnings, and key context distilled from past sessions during compile (the βdreamingβ step). Loaded every session so Ace wakes up knowing where things stand. | 2.0 KB |
| β | projects/TASKS.mdA high-level overview of every task across projects β priorities, whatβs overdue, whatβs being worked on right now. A distilled snapshot, not the full per-task detail, so Ace sees the lay of the land without loading every task file. | 2.4 KB |
Path-scoped rules3 active
| rule | applies to | size |
|---|---|---|
| mobile project | apps/mobile/** | 88 B |
| sql project | **/*.sql**/migrations/** | 106 B |
| typescript project | **/*.ts**/*.tsx | 114 B |
Injected at SessionStart1.0 KB
| entry | size | |
|---|---|---|
| β | today's date Tuesday, October 27, 2026 | |
| β | session tail 2026-10-27.md | 454 B |
| β | today's reports 3 entries | 353 B |
| β | pinned reports none pinned | 0 B |
| β | history 1 snapshot | 45 B |
Daily memory14-day retention
2026-10-27Reconciliation walk; exporter bug root-caused and filed as pf-099.
2026-10-26Load-test target locked at 5x; reconciliation dashboard specced.
2026-10-25SOC 2 evidence sprint; 3.2 release checklist walked and submitted.
Learningshow Ace self-corrects
Lead with the number. Alex reads the first line only unless it earns the rest.
Never page before checking the runbook.
Staging data is not production data; confirm funnel numbers on production before a board brief.
Pendingopen loops Ace is tracking
pf-104 load test Β· staging booked for Thursday.
cp-031 access reviews Β· 3 of 5 systems done; Okta and AWS remain.
Senior platform engineer hire Β· two onsites this week.
Active threads5 live
π v2 launch Β· window locked for 2026-11-10; marketing page staged, changelog drafted. pf-104 load test is the last gate.
π― SOC 2 Type II Β· fieldwork starts 2026-11-24; evidence 80% done, cp-031 due this week.
π¨ Billing migration (Stripe to usage-based) Β· dual-write live since 2026-10-21; cutover gated on pf-101.
π± Mobile 3.2 Β· in App Store review; the push opt-in experiment is queued behind it.
π Activation leak Β· step-2 drop-off 38% to 31% after the email rework; gr-012 is the next lever.
Recent decisions
2026-10-26 β Load test at 5x peak, not 10x: 10x costs three extra days and the v2 traffic model doesn't justify it.
2026-10-25 β Billing cutover hard date set, gated on the dual-write reconciliation report.
2026-10-23 β Incident runbooks live in the brain, not the wiki; every postmortem ends with a runbook diff.
2026-10-21 β Two-pass agent code review team-wide.
2026-10-18 β Empty-state redesign over the pricing experiment: step 2 is the leak, not the paywall.
activation-funnel β Step-by-step activation model and where Acme leaks new workspaces
agentic-code-review β Two-pass agent review: correctness first, then simplification
brain-fed-planning β Weekly planning that starts from the compiled brain, not a blank doc
incident-runbook-loop β Every postmortem ends with a runbook diff in the brain
Compile pipelineΞ£ $4.76
| sessions ingested | 7 |
| pending | 0 β fully absorbed |
| last compiled | 30m ago |
| inbox to absorb | 1 |
Memory footprint
| curated wiki | 4.7 KB |
| memory index | 2.0 KB |
| learnings | 3 |
| daily memory files | 3 (14-day retention) |
| feedback log | 105 B |
Last lint run2026-10-27T13:08:00-04:00
| errors | 0 |
| warnings | 1 |
| suggestions | 1 |
| report | open lint.md |
Issues2
WARNActive Threads bullet 1 is 262 characters (budget 250)
SUGGESTIONconcepts/brain-fed-planning has no inbound links
Reports
Briefings, plans, and audits Ace has produced. Click any title to open it.
2026-10-27
2026-10-26
Scheduler β°
Recurring routines and when to run them β manual for now.
Sync (morning)manual
Daily Β· 07:00
next Wed, Oct 28 tomorrow
/agent-kevin:sync
Sync (evening)manual
Daily Β· 19:00
next Tue, Oct 27 today
/agent-kevin:sync
Weekly goalsmanual
Mondays Β· 08:00
next Mon, Nov 2 in 6d
/agent-kevin:goals week interview
Monthly goalsmanual
1st of month Β· 08:00
next Sun, Nov 1 in 5d
/agent-kevin:goals month
Yearly goalsmanual
Quarterly Β· Jan/Apr/Jul/Oct 1 Β· 08:00
next Fri, Jan 1 in 66d
/agent-kevin:goals year
Self-reviewmanual
15th of month Β· 08:00
next Sun, Nov 15 in 19d
/agent-kevin:self-review
Capabilities
Everything you can ask Ace to do β skills by name, tools under the hood.
| when | say | what happens |
|---|---|---|
| Morning and evening | /agent-kevin:sync | Full refresh β compile, lint, flywheel, dashboard β then a briefing. Picks the briefing automatically: morning if none ran today (even in the afternoon), evening once it has or past 9pm (or say `sync morning` / `sync evening`). |
| Between sessions | /agent-kevin:briefing pulse | A fast status check without the heavy maintenance pass. |
| Feeling lost | /agent-kevin:attention checkpoint all | A checklist for each recent session β what got done, where it stands, what waits on you, how to resume it. |
| After a busy day | /agent-kevin:knowledge-compile | Absorb captured sessions, feedback, and inbox drops into long-term memory. |
| 1st of the month | /agent-kevin:goals month | Set the monthβs themes and big rocks (`goals week` does the same per week, `goals day` for today). |
| Quarterly | /agent-kevin:goals year | Plan the year ahead quarter by quarter β run mid-year it shapes the remaining quarters; run in Q4 it drafts next year from Q1. |
| Once a month | /agent-kevin:self-review | Sync asks when it is due. Cleans up stale tasks, quiet projects, outdated memory and articles with you, then turns your feedback into better rules. |
| Save anything | βcapture this: <url, text, or file>β | Drops it into the inbox; the next compile absorbs it into the wiki. |
| Jot something down | /capture <text> | Saved to the inbox at once, with no reply to wait for (Claude Code; `/lesson <text>` does the same for a correction). |
| Line up the next ask | /queue <prompt> | Sent once the current task ends, one per turn, never mid-task (Claude Code; `/queue clear` drops the rest). |
| Find what this session made | /reports | The reports and project pages this conversation wrote, in a row above the prompt (Claude Code; `/reports attach <path>` adds any file). |
| File work | βcreate a task in <project>: β¦β | New task file with id, priority, and due date; shows up here and in TASKS.md. |
| Taxes and receipts | /agent-kevin:tax <whatβs due | receipt | close | help> | Tax deadlines as dated tasks, receipts filed to the ledger, monthly close for the accountant; nothing is filed or paid without you. |
| Support queue | /agent-kevin:helpdesk pulse | Open tickets ranked, patterns across them and tickets to raise, saved to reports/helpdesk/; replies are drafted as private notes, never sent. |
| Grab a page | βscreenshot https://β¦β | Headless-browser PNG into reports/captures/. |
| Make a PDF | βturn <file or url> into a styled PDFβ | Markdown/page rendered to PDF (mermaid included) in reports/captures/. |
| Research something | βresearch <topic> and write it upβ | Web research with sources, persisted as a report you can reread. |
| Reviewing a PR | /agent-kevin:engineer review <number> | Verified findings with paste-ready comments for a teammateβs PR; `engineer replies <number>` drafts replies and uncommitted fixes for your own. Reports land in reports/reviews/. |
| Presenting or recording your own PR | /agent-kevin:engineer walkthrough <number> | Standup script, diff tour in scroll order, the questions reviewers will ask with receipts, and a scene-by-scene recording runbook for your PR. Lands in reports/reviews/. |
| Second modelβs pass on your work | /agent-kevin:adversarial-review | Writes the brief another model reviews from (a PR, a branch, an uncommitted tree, or a plan), then verifies its findings, fixes the real ones, and refreshes the brief; one dossier in reports/reviews/ for every round. |
| Refresh this page | /agent-kevin:dashboard | Regenerates this dashboard (and TASKS.md) from current state. |
/agent-kevin:adversarial-review auto
Cross-model adversarial review of your own work, as a loop on one dossier in `<HOME>/reports/reviews/`: a PR, a branch, an uncommitted working tree, or a plan,β¦
/agent-kevin:api-collections auto
Draft API requests as collection files the operator opens, visualizes, and fires in their API client (adapters β Bruno and Postman shipped, plain-curl fallbackβ¦
/agent-kevin:attention auto
The operator's day in one place: what today is for, what slipped, the week and month, the roadmap in flight, who is waiting on them, and where each session lefβ¦
refreshaddplanorganizestandupcheckpointbackfill
/agent-kevin:briefing auto
The day's bookends and a quick check.
morningeveningpulse
/agent-kevin:browser-flows auto
Drive a website in a VISIBLE browser to run real, repeatable flows end to end β scrape a page into structured data, fill a form, or click through a multi-step β¦
/agent-kevin:configure-skills auto
Configure Kevin's optional skill packs (SEO, Browser, Database, GitHub, API, Xcode, Helpdesk) or author a brand-new custom skill.
/agent-kevin:dashboard auto
Refresh and open the Agent OS dashboard β a static HTML mission-control page covering today's attention view and activity, work across projects, sessions, Keviβ¦
/agent-kevin:engineer auto
Engineering rigor for code work in a repository: fix a bug, build or change a feature, refactor or simplify, chase a slowdown or hillclimb a metric, prototype β¦
investigationhowwhybug fixfeaturesimplifyrefactoringperformancehillclimbruntime forensicstrace forensicsvisual parityblast radiusprototypefigure it outautonomous runpause safelysession pickupauthoring a skillevalverification skillpr reviewpr repliespr walkthrough
/agent-kevin:find-session auto
Find a specific past Claude Code session by what it worked on β a branch, a PR number, a worktree, a bug, a feature, a task id β and hand back its resume commaβ¦
/agent-kevin:flywheel auto
Cross-project work session.
/agent-kevin:goals auto
Goals from today to the year, written to the goal blocks in TASKS.md; the attention skill plans the days around them.
dayweekmonthyear
/agent-kevin:guide auto
Write a guide someone else can follow as a polished HTML page: a setup walkthrough, onboarding, or how a workflow runs end to end and who does what.
/agent-kevin:helpdesk auto
SupportCandy or Pylon tickets.
setuppulsestatsticketaccountdraftreviewsraiseworkflow
/agent-kevin:history auto
Turn on version history for the agent's memory, so any change to what it knows can be seen and undone.
/agent-kevin:humanizer auto
Remove signs of AI-generated writing from text.
/agent-kevin:init
Guided first-run onboarding for the agent-kevin plugin.
/agent-kevin:itinerary auto
Plan a trip end-to-end and generate a polished, interactive, print-ready HTML itinerary.
/agent-kevin:knowledge-compile auto
Compile raw session logs, feedback, and inbox items into structured wiki articles.
/agent-kevin:media auto
Make sense of a local audio or video file: transcribe the speech on-device with timestamps, grab screenshots, summarize what was said and shown, turn a bug-repβ¦
summarizetickettranscribescreenshotsremember
/agent-kevin:mermaid auto
Validate and iterate on a Mermaid diagram before it ships.
/agent-kevin:plan-spec auto
Deep-dive specification writer that reads input files, interviews the user with Socratic questioning, and produces a comprehensive spec document.
/agent-kevin:project auto
Start, retire, or hand off project work.
createarchivehandoff
/agent-kevin:release
Producer-only.
/agent-kevin:rename-agent
Rename this agent's display name across an existing HOME β the Name in IDENTITY.md, the emoji and avatar, and every mention in the markdown the agent reads nowβ¦
/agent-kevin:roadmap auto
Build or update a strategic roadmap as a polished, self-contained HTML surface β timeline lanes over a directional rail, milestone cards, outcome bands, dark/lβ¦
/agent-kevin:seed auto
Hand this agent to a teammate, or take one on.
exportimport
/agent-kevin:self-review auto
Monthly upkeep of the agent's brain and rules, with the operator.
brainrules
/agent-kevin:seo auto
Search evidence for a site, read-only: a full audit (Search Console + PageSpeed + on-demand SERP checks, ranked findings, a written report), Search Console queβ¦
auditconsolespeedserprank
/agent-kevin:setup-worktree auto
Create a git worktree for parallel work, as a sibling of the repo, and bootstrap it ready to code: copies the gitignored local files from the main checkout, inβ¦
/agent-kevin:sync auto
End-to-end refresh β fast-forward configured code repos, compile pending raw inputs, lint and fix the wiki, run a flywheel pass, surface what needs attention (β¦
/agent-kevin:tax auto
Bookkeeping and tax compliance for the operator's companies and personal return: what tax is owed right now, deadlines as dated tasks, receipt capture, monthlyβ¦
setupcalendarpositioncapturecloseestimateaccountantoptimizeyear-end
/agent-kevin:upgrade auto
Apply pending HOME migrations after a plugin code update.
/agent-kevin:wordpress-rest auto
Query WordPress content via the public WP REST API β posts, pages, custom post types, categories, tags, media, and modified dates.
appstore_reviews
Read App Store reviews for any app, newest first: rating, title, text, the reviewer's nickname, app version, date and storefront, with rating counts.
attention_write
Render attention (today, carried over, this week, this month, the roadmap in flight, and a queue of what's waiting on the operator).
browser_flows
Run a browser-flows flow that drives a site in a VISIBLE browser (the operator can log in manually when a flow needs it β no API keys).
browser_markdown
Render a URL or local file in chromium so JS-rendered content hydrates, then extract the article body via Mozilla Readability and convert to Markdown.
browser_pdf
Render a URL or local file (HTML or Markdown) to PDF.
browser_record
Drive a browser through scripted steps and return a video file.
browser_screenshot
Capture a PNG screenshot of a URL or local HTML/MD file.
capture
Capture any input (a thought, snippet, dropped file, URL) into the agent's raw tree for the next knowledge-compile to absorb.
codex_setup
Generate or regenerate this home's Codex wiring (.codex/hooks.json, the MCP registration and permission profile in .codex/config.toml, and .codex/rules/<agent>β¦
compile_next
Return the next compile work item: a rendered prompt + source content + metadata.
compile_status
How many raw items are pending compilation (sessions/feedback/inbox).
compile_write
Mark a compile work item complete.
curl_run
Fire ONE curl request with collection-scoped secrets, returning transcript-safe output.
dashboard
Rebuild both derived views in one pass: projects/TASKS.md (task dashboard from frontmatter β Active, Blocked, Overdue, Stale, Recently Closed; preserves the goβ¦
database_fork
Fork (clone) a database on a LOCAL Postgres server so you can make heavy or destructive schema changes without touching the shared/live one β for a worktree, aβ¦
database_list 0 databases
List the Postgres connections available to query.
database_query 0 databases
Run a read-only SQL query against a configured Postgres connection.
database_schema 0 databases
Inspect a Postgres database structure (read-only).
github_comment_update
Replace the text of your own comment on an issue or a pull request's conversation (writes to GitHub; the old text is gone).
github_fast_forward
Fast-forward the default branches (main||master and develop||dev) of the configured local checkouts so the agent grounds against current code.
github_issue_comment
Comment on a GitHub issue (writes to GitHub, visible to everyone with repo access), optionally with screenshots or videos attached.
github_issue_create
Open a GitHub issue (writes to GitHub, visible to everyone with repo access).
github_issue_list
List issues for a repo (read-only).
github_issue_update
Change a GitHub issue's title, description, labels or milestone (writes to GitHub).
github_issue_view
View one issue in full (read-only): body, labels, assignees, milestone, comments, state/close reason, and timestamps.
github_pr_checks
Status of every check on a pull request (read-only): name, state, bucket (pass/fail/pending/skipping/cancel), workflow, and a link.
github_pr_comments
Every comment on a pull request (read-only): inline review threads with their file/line anchor and resolved + outdated state, review submission bodies, and topβ¦
github_pr_create
Open a pull request from a branch already pushed (writes to GitHub, visible to everyone with repo access).
github_pr_diff
The unified diff of a pull request (read-only).
github_pr_list
List pull requests for a repo (read-only).
github_pr_update
Replace a pull request's title or description (writes to GitHub; the old text is gone).
github_pr_view
View one pull request in full (read-only): body, latest reviews, conversation comments, changed files, diff stats, label/review state, mergeability, the head cβ¦
github_run_list
List GitHub Actions workflow runs for a repo (read-only).
github_run_log
Logs for a workflow run (read-only).
github_run_view
View one workflow run (read-only): overall status/conclusion plus the per-job, per-step breakdown so you can see which job and step failed.
google_auth
One-time Google OAuth2 consent flow.
gsc_inspect
Inspect a single URL's indexing status via the URL Inspection API.
gsc_query
Search analytics rows for the configured site.
gsc_sites
List all sites/properties accessible to the authenticated GSC user.
helpdesk_accounts
List the helpdesk's accounts (customer companies): id, name, domains, tags and owner.
helpdesk_assign
Assign a helpdesk ticket to a teammate (an id from helpdesk_lookups teammates), so a person picks it up.
helpdesk_attachment
Download one ticket attachment (a log, a screenshot) by the id helpdesk_ticket listed, into a fresh temp folder outside the home, and return its path.
helpdesk_connections
List the configured helpdesk connections: each helpdesk, its connection name (absent for the default) and its site where that is not a secret.
helpdesk_lookups
List one kind of helpdesk reference data as id + name: statuses and categories (SupportCandy), teammates (both; with email on Pylon), tags and macros with theiβ¦
helpdesk_note
Add a private note to a helpdesk ticket: visible to agents, never to the customer.
helpdesk_stats
Count the helpdesk tickets in the given statuses updated within a window (default the last 24h): total, by status, by tag (by category on SupportCandy; a tickeβ¦
helpdesk_ticket
Fetch one helpdesk ticket with its whole conversation, oldest first: the ticket's opening body when the helpdesk keeps it apart, linked engineering issues and β¦
helpdesk_tickets
List helpdesk tickets updated within a lookback window, newest first: id, number, subject, status, category or tags, requester and assignee (name, email where β¦
home_history
Version history for this agent home.
knowledge_lint
Run structural health checks across the wiki (broken links, orphan pages, orphan sources, missing backlinks, sparse articles, transient memory refs in permanenβ¦
links_rewrite
Normalize bare task IDs and shorthand references into [[wikilinks]] across the knowledge base.
list_worktrees
Audit every registered worktree of a repo β the accumulated-worktrees triage tool.
media_transcribe
Transcribe the speech in a LOCAL audio or video file, on-device (macOS 26+ via `yap`, `brew install yap`; audio never leaves the machine).
memory_prune
Delete daily memory files older than the retention window (default 14 days).
open_page_rank
Get OpenPageRank score for up to 100 domains.
page_speed_audit
Run PSI for both mobile + desktop in parallel.
page_speed_psi
Lighthouse PageSpeed Insights slice for one URL+strategy.
ping
Health check β returns server status, the plugin version this server process loaded, and resolved paths.
remove_worktree
Tear down a git worktree safely, running outside the Bash sandbox so `git worktree remove` can write the main repo's .git/config.
report_write
Write a report file to reports/<category>/ AND insert a one-line entry into reports/index.md under today's date heading.
run_upgrade
Run the versioned upgrade migration at skills/upgrade/scripts/<version>.ts, outside the Bash sandbox (so it can touch deny-gated paths).
seed_export
Build a seed bundle zip from an APPROVED selection β call only after the seed export interview + per-file review gate.
seed_import
Overlay a seed bundle onto THIS initialized home (fork semantics β imported files become the recipient's own).
seed_scan
Read-only: detect what this home could hand a teammate as a seed bundle β agent name (custom vs template), identity divergence, concepts (template-identical flβ¦
serpapi_search
Real Google SERP data: organic results, ads, AI overview, shopping, PAA, knowledge graph.
setup_worktree
Create a sibling git worktree and bootstrap it (copy gitignored local files β install deps β build), running outside the Bash sandbox so git can write .git/conβ¦
task_close
Close a task as done (status=done, closed=today).
task_create
Create a new task.
task_get
Read a single task file in full (frontmatter + description + checklist + thread).
task_query
List tasks across all projects, optionally filtered by status/priority/project/assignee/horizon lane.
task_scan
Resolve cross-task state: auto-unblock, auto-block, surface overdue, due-soon (next 14 days) and stale tasks, plan priority bumps.
task_thread
Append a message to a task's thread section.
task_update
Update fields on an existing task.
video_frames
Extract still frames from a LOCAL video file for visual analysis, running outside the Bash sandbox so it can read videos in ~/Downloads, ~/Desktop, ~/Documentsβ¦
web_search
Search the web via Perplexity.
Usage
${CLI} <group> <command> [flags]
Groups
ping
Print resolved paths + timezone (sanity check)
hosts
Check the installed Claude Code / Codex CLIs against the plugin's version floors (--codex: require Codex); exit 1 below a floor
capture
Capture text / a file / stdin into raw/inbox/ (or feedback.md) for the next compile
session-capture
Ingest a session transcript into raw/sessions/<today>.md (called by Claude Code hooks)
session-start
Emit dynamic context (today / last session tail / git activity) for the host's SessionStart hook
statusline
Render Claude Code's footer from the status-line JSON on stdin (--subagent: the agent panel rows; --setting: the settings entry)
task
Read + mutate task files under projects/*/tasks/
compile
Knowledge-compile state (synthesis runs in Claude Code, not here)
knowledge
Wiki maintenance (lint)
notices
What to nudge the operator about (upgrade, sync) as JSON; \`notices record <id> --outcome=acted|snoozed\` logs what they did
prune
Delete memory/YYYY-MM-DD*.md older than 14 days
links
Rewrite bare task IDs + shorthand into [[wikilinks]]
dashboard
Rebuild the Agent OS dashboard at <HOME>/dashboard.html + projects/TASKS.md (open in any browser)
worktree
Create a sibling git worktree of <repoPath> and bootstrap it (copy locals β install β build); \`worktree remove\` tears one down safely
seed
One-shot agent handoff: scan what this home could seed a teammate with, export a reviewed selection as a zip bundle, import a bundle into a fresh home
database
Query/inspect/fork local Postgres via AGENT_DB_<NAME> connections (real terminal β outside the Bash sandbox)
Task commands
task query [--status=X] [--priority=P0-P3] [--project=NAME]
task get <id>
task create --project=NAME --title=... --description=... [--priority=P2] [--type=task|bug|idea|epic] [--due=YYYY-MM-DD] [--horizon=today|week|next-week|month|later] [--labels=a,b] [--depends_on=id1,id2] [--parent=ID] [--checklist=item ...]
task update <id> [--status=X] [--priority=X] [--title=X] [--due=YYYY-MM-DD] [--horizon=X] [--blocked_by=X] [--labels=a,b] [--depends_on=id1,id2] [--parent=ID] [--issue=URL] [--description=...]
task close <id>
task thread <id> --message=... [--type=quote|info|warning]
task scan
Resolve dependencies, surface overdue/stale/auto-* changes
Capture commands
capture "the thought"
Write inline text to raw/inbox/<ts>-<slug>.md (next compile distils it)
capture --file=PATH
Capture a file's contents into raw/inbox/
capture --url=URL
Fetch a URL, strip HTML noise (<script>/<style>/<head>), store with source: url:<url> in frontmatter
capture --stdin
Read content from stdin (e.g. \`pbpaste | ${CLI} capture --stdin\`)
capture ... --kind=feedback
Append to raw/user/feedback.md instead of inbox/ (corrections/preferences)
capture ... --title=X --label=Y
Optional metadata (slug source + frontmatter label)
Hook commands (internal β wired into Claude Code hooks; safe to run manually for testing)
session-capture --mode=session-end|pre-compact --hook-protocol=claude
Read hook JSON from stdin and append the transcript to raw/sessions/.
session-capture --mode=... --transcript=PATH --cwd=PATH --session-id=X
Plain-CLI mode β same logic without the hook envelope. Useful for testing.
session-capture ... --format=claude (default)
Transcript-format adapter (claude, codex).
session-start [--hook-protocol=claude|codex]
Emit dynamic SessionStart context. Without the flag, prints the structured result for testing.
session-start|session-capture ... --home=PATH
Pin the agent home from the command line (how the per-home Codex hooks name it)
guard [--hook-protocol=claude|codex]
PreToolUse hook: read the tool call from stdin and exit 2 when a shell command would write a home tree (knowledge/, projects/, reports/) relative to a cwd outside the home, leave the session outside the home (claude only: a cd carries over there), or find scratch in the shared temp dir by pattern or a hand-picked $TMPDIR name
Knowledge commands
knowledge lint [--fix]
Structural health check; --fix rewrites stale wikilinks + inserts backlinks
seed scan
Detect what this home could seed a teammate with (read-only JSON)
seed export --include=p1,p2 --name=AGENT [--out=PATH]
Build a seed bundle zip from home-relative paths (no review gate here β you are the gate)
seed import <bundlePath> [--overwrite] [--dry-run]
Overlay a bundle onto THIS home; --dry-run prints the plan + conflicts first
Compile commands
compile status
Show queue (pending sessions, feedback, inbox)
compile next
Print next work item (no synthesis β run /${PLUGIN}:knowledge-compile for that)
compile write <itemId>
Mark item complete (advanced β synthesis writes use this internally)
Worktree commands
worktree <repoPath> --branch=BRANCH [--base=REF] [--slug=SLUG] [--extra=sub1,sub2]
Create <repoPath>-<slug> as a sibling of the main checkout, copy gitignored locals, install, build. A bare --branch is namespaced under the operator (<operator>/<name>). --base picks the start-point (default: dev β develop β main β master β current HEAD). --extra lists relative subdirs with their own lockfile. NOTE: blocked by the Bash sandbox when run from inside Claude Code (git can't write .git/config) β use the setup_worktree MCP tool there; this CLI is for a real terminal.
worktree list <repoPath>
Audit every registered worktree: branch, dirty/unpushed counts, ahead/behind and merge state vs the base ref, last-commit age, and a verdict (deletable / uncommitted / unpushed / pushed-unmerged / missing / base / main). Read-only β fine anywhere.
worktree remove <worktreePath> [--delete-branch] [--force] [--dry-run]
Safely remove a worktree: refuses on a dev/develop/main/master worktree and on uncommitted changes; needs --force when the branch has committed-but-unpushed commits; runs the repo's \`clean\` script first. Keeps the branch unless --delete-branch. --dry-run reports the status without touching anything. Same sandbox note β use remove_worktree there.
Database commands
database list
List configured AGENT_DB_<NAME> connections (name + host/db, never credentials)
database schema --connection=NAME [--table=T] [--schema=S] [--database=DB]
List user tables, or describe one table's columns (read-only)
database query --connection=NAME --sql="SELECT ..." [--database=DB] [--timeout=MS]
Run read-only SQL (server-enforced READ ONLY tx; writes/DDL rejected)
database fork [--connection=NAME] [--source=DB] [--fork=NAME] [--cwd=PATH] [--repoint-env] [--env-var=DATABASE_URL] [--force] [--terminate-source] [--drop]
Clone a LOCAL database via CREATE DATABASE ... TEMPLATE. Fork name defaults to <source>_<git-branch> when --cwd is a repo, else <source>_fork. --repoint-env writes a .env.local override in --cwd; --drop tears the fork down. Remote hosts refused.
Environment
AGENT_HOME=<path>
Override agent home (default: cwd)
AGENT_PROJECTS=<path>
Override projects/ location (default: <HOME>/projects)
AGENT_KNOWLEDGE=<path>
Override knowledge/ location (default: <HOME>/knowledge)
AGENT_TIMEZONE=<tz>
Override timezone (default: system tz)
Examples
${CLI} capture "remember to follow up with the accountant on the annual filing"
${CLI} capture --file=~/notes/board-meeting.md --title="Board meeting 2026-05-28"
${CLI} capture --url=https://docs.anthropic.com/en/docs/claude-code/overview
pbpaste | ${CLI} capture --stdin --title="Clipped article"
${CLI} capture --kind=feedback "don't propose git push for local-only repos"
${CLI} task query --status=active
${CLI} task create --project=blog-dev --title="Draft launch post" --description="..." --priority=P1
${CLI} dashboard
${CLI} worktree /path/to/repo --branch=feat/my-thing
${CLI} knowledge lint --fix
${CLI} compile status
${CLI} database list
${CLI} database query --connection=app --sql="select count(*) from users"
${CLI} database fork --connection=app --cwd=/path/to/worktree --repoint-env
In-process hooks for interactive Claude Code 2.1.293 or newer. Codex and claude -p run without them: the CLI covers the commands and the session banner carries the notices. Not seen loading on this machine yet.
Instant commands
Capture a thought, log a lesson, close a task, see today or copy this conversation's session id, answered at once without a model turn.
slash commands Β· the Today and Session rows above the prompt
/capture <text>/lesson <text>/done <task-id>/today/session
Repo manuals
The first file read or written in a granted code repo, or named by absolute path in a shell command, attaches that repo's CLAUDE.md or AGENTS.md, once, and again after a compaction or /clear.
tool results Β· a π line above the prompt
/manuals
Session reports
The reports this conversation wrote or edited, its own and its subagents', its project documents and anything attached by hand, until dismissed; a report with an HTML page shows the page.
slash command Β· a π row above the prompt
/reports [attach <path>β¦]
Sync progress
Sync's step, elapsed time and what it is clearing, live while it runs; its report quotes counted numbers instead of a tally.
above the prompt
sync_stats
Notices
The top upgrade or sync nudge, with a button that runs it and one that snoozes it until tomorrow; also the Tab suggestion.
above the prompt Β· toast for an alert
Queue a prompt
Line up prompts while a task runs; each goes out as its own turn once the one before it ends, never mid-task.
slash command Β· a β³ count above the prompt
/queue <prompt> | clear
Setup prompt
In a folder that isn't an agent home yet, a row with a button that runs init; also the Tab suggestion.
above the prompt
SessionStartFires when a session starts. Injects todayβs date, the tail of your last session, todayβs reports, the reports you pinned, recent git activity, and a warning when the home needs an upgrade or a fix β so Ace wakes up with continuity instead of a blank slate.kevin session-start --hook-protocol=claude
SessionEndFires when a session ends. Captures the full transcript to
knowledge/raw/sessions/YYYY-MM-DD.md. This is how every session is saved β later compiled into long-term memory.kevin session-capture --mode=session-endPreCompactFires just before Claude Code compacts (summarises) a long conversation. Captures the session up to that point so the part being compressed away is still preserved on disk.kevin session-capture --mode=pre-compact
PreToolUsekevin guard --hook-protocol=claude
Alex Chen π€
Who Ace is working for β compiled from every session.
Alex Chen
America/New_York
Co-founder and CTO of Acme, a B2B logistics SaaS scaling past launch. Previously staff engineer at two startups through Series B. Writes Go and TypeScript; reviews everything touching billing.
Role
- Owns platform, billing, and the SOC 2 track.
- Runs the Monday planning review and the weekly launch standup.
Working Hours
- 10:00-19:00 ET. The deep-work block before noon is sacred: no meetings, no pings.
Signal Topics
- Agentic coding tools and review workflows.
- Usage-based billing and revenue recognition.
- Logistics software and freight tech.
Go deeper3 facets
Ace π€
Your life co-pilot β who he is and how he runs.
Company agent (agent-acme, forked from agent-kevin)
Sharp but approachable. Gets things done. Knows the codebase and the company.
Ace is Acme's private company agent. It pairs with engineering on real tickets, compiles the company's knowledge into a living brain, and briefs leadership every morning. Self-hosted on Acme infrastructure; nothing leaves the building.
Core Rolefrom IDENTITY.md
- Agentic engineering: coding, debugging, monitoring, and planning with full company context.
- Company brain: capture, compile, and serve institutional knowledge.
- Daily briefings, task tracking, and incident support.
Vibefrom SOUL.md
- You are Ace, Acme's company agent. Sharp, direct, allergic to fluff. You ship with the engineering team daily and brief the leadership floor every morning. Clever over polite; useful over impressive.
Operational Patternfrom IDENTITY.md
- Briefings. The morning brief carries priorities plus signal-topic and industry news; the evening wrap is a today-only delta.
- Code. The engineer skill for platform work and teammates' PRs.
- Review loop. Ace implements; a second model reviews on one dossier, and Ace verifies every finding against the code.
Writing Stylefrom SOUL.md
- Lead with the number. Tables and before/after blocks over paragraphs.
- ASCII diagrams in chat; Mermaid in files.
Core Truthsfrom SOUL.md
- Do the thing. Explain after, not before.
- Verify before you claim. A number gets a source or it stays out.
- Have a spine. Recommend once, then build to the call.
- Figure it out. Read the file, check the context, then ask.
Boundariesfrom SOUL.md
- Customer data stays inside Acme systems.
- When in doubt, ask before acting externally.
Files
Ace's character and role β edit these to evolve them.SOUL.md Β· IDENTITY.md
Runtime
| version | v0.8.8 |
| plugin | agent-kevin@agentlayer |
| marketplace | agentlayer (github) |
| plugin path | /home/alex/.claude/plugins/marketplaces/agentlayer |
| home | ~/agent-acme |
| timezone | America/New_York |
| history | managed by your own git setup |
System
The machinery β settings, logs, releases.
Settings layers3 allow Β· 1 deny total
| scope | file | allow | deny | env |
|---|---|---|---|---|
| user | ~/.claude/settings.json | 0 | 0 | 2 |
| project | ~/agent-acme/.claude/settings.json | 3 | 1 | 0 |
| local | ~/agent-acme/.claude/settings.local.json | 0 | 0 | 2 |
Plugin
| plugin | agent-kevin@agentlayer |
| marketplace | agentlayer (github) |
| plugins enabled | skill-creator Β· typescript-lsp Β· agent-kevin |
Environment4 vars
| key | value | scope |
|---|---|---|
AGENT_HOMEThe agent home directory β the root of the knowledge tree, projects, and reports. The MCP server resolves every path from here. Defaults to the directory you launch Claude from; set it in ~/.claude/settings.json only on a machine with exactly one agent home, since a machine-wide value points every agent at the same home. | ~/agent-acme | user |
| CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICTurns off non-essential network traffic (telemetry, auto-update pings, etc.) β keeps Claude Code quiet on the wire. | 1 | user |
| AGENT_HOME_TIMEZONE | America/New_York | workspace |
AGENT_CODE_PATHAbsolute path to your primary codebase. Used by the setup-worktree skill and exposed as $AGENT_CODE_PATH. | ~/acme/platform | workspace |
Secrets0 set Β· values never shown
No secrets configured. Add keys to .state/secrets/.env (loaded at boot, never displayed).
Health
| file | ~/agent-acme/.state/logs/app.log (206 B) |
| today | 1 warn Β· 0 err |
| all-time | 1 warn Β· 0 err |
Tail145 B
2026-10-27T17:17:17.930Z INFO [π€ system] [cli] dashboard2026-10-27T17:15:17.930Z WARN [π€ system] [cli] compile: one inbox item deferred
v0.8.8 Β· your baseline2026-10-28
Added
- **A checkpoint is a checklist.** `/attention checkpoint` writes this session as done steps with their proof, what is in progress, the next step, decisions waiting on the operator with a recommended pick, traps, and what changed since the last checkpoint. `/attention checkpoint all` writes the same checklist for every recent session: the waiting decisions first, ranked, then a card per session, then an offer to jump to one. A session that already wrote a checkpoint has it reused, with the turns since counted. It replaces the where-am-i paragraphs and the triage interview.
- **The dashboard's session radar reads checkpoints.** The Today feed shows each session's in-progress step, or its next step when nothing is in progress (older reports fall back to the whole card), and the Recent tab keeps one line per step.
- **Explainers gain step-through walkthroughs and clickable UI mocks.** A walkthrough is a diagram with scenario tabs, play and step controls, a timeline and a detail panel, deep-linked by `#wt=scenario.step`. A mock is a fake screen with states, dialogs, selection, drag to reorder, remove with Undo, toasts and tabs. The explainer check refuses a step that names a missing part and a mock control that leads nowhere.
Changed
- **The focus skill is now `attention`.** Claude Code ships a built-in `/focus`, so `/agent-kevin:focus` never reached the skill. The skill, its playbooks, the `focus_write` tool (now `attention_write`), project pages (`attention.html`), the dashboard view and the Codex default prompt all follow the new name. `where-am-i` and `triage` are gone: use `/attention checkpoint all`.
- **SOUL: "I didn't read that" restarts step by step.** The agent restarts with the answer in three lines or fewer, then walks through the rest one short step per reply, waiting for "next", and keeps that size for the rest of the conversation.
- **Retired MCP tools migrate like retired skills.** Upgrade's baseline check and seed import map a retired tool's grant to its successor in the same `allow`, `ask` or `deny` list, so a dead grant never comes back and a gate the operator placed carries over.
Fixed
- **A worktree on a base branch is never torn down.** A worktree on `dev`, `develop`, `main` or `master` could read `deletable` and be removed (with its branch, under `deleteBranch`). `list_worktrees` now gives it a `base` verdict, `remove_worktree` refuses it, and the teardown offer leaves it out.
- **A stalled Chromium launch retries instead of hanging the capture.** Under bun, Chromium's DevTools pipe sometimes breaks at startup and Playwright waited out its 180s timeout, past the host's 120s tool budget. Each launch now gets 20s and up to three attempts, for the screenshot, PDF, markdown and record tools and browser flows.
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.8.8.ts. It moves each `projects/<slug>/focus.html` to `attention.html` (an existing `attention.html` wins and the old page goes, since the dashboard re-renders it), moves the queue cache from `.state/focus/` to `.state/attention/` (or drops it when the new one exists; it refills on the next pull), and rewrites any `focus_write` or retired `Skill(agent-kevin:focus)` rule in `.claude/settings.json` and `.claude/settings.local.json` to its successor in the same `allow`, `ask` or `deny` list. Both settings files are read first, so one that doesn't parse stops the run with nothing changed. Idempotent. |
template/AGENTS.md | mandatory | the memory-routing row and the `reports/radar/` tree comment name the attention skill's standup and checkpoint all instead of focus's standup and where-am-i. |
template/SOUL.md | optional | a Writing Style line: "I didn't read that" (or "too long") restarts with the answer in three lines, then one short step per reply. |
manual | none | `/agent-kevin:focus` is now `/agent-kevin:attention`, and `/focus where-am-i` and `/focus triage` are `/attention checkpoint all`. Plain asks ("what should I work on", "which session needs me") route there on their own. A schedule or script outside the home that runs an old command needs the new one. |
v0.8.72026-10-26
Added
- **The agent can assign a helpdesk ticket.** `helpdesk_assign` hands a SupportCandy ticket to a teammate (an id from `helpdesk_lookups` teammates), then reads the ticket back and fails when the teammate isn't on it, so a write the site quietly ignores never reads as done. The connection's agent role needs **Assign Agents** for the ticket's assignment state. Pylon tickets can't be assigned yet. The Helpdesk pack grants it beside `helpdesk_note` at the recommended level.
- **A queue routine can write its notes and assignments without asking.** When a profile's `## Workflow` says its private notes and assignments go ahead without asking, the routine writes those two unasked and its output lists every ticket with what was written. A sweep that notes each new ticket and hands it to a person no longer waits on a yes per ticket. Cards, tasks and comments still wait, and nothing replies, closes or changes a status. The setup interview asks this for each routine.
- **Explainer and PR report diagrams match the page, and code is highlighted.** Mermaid takes its colours from the page in light and dark, and code blocks are highlighted (diff lines show added and removed). The explainer check flags a raw `<` in a code block, which a browser reads as a tag and drops the rest of the line.
Fixed
- **Untrusted content can't close its wrapper early.** A wrapper tag spelled inside a ticket body, a review or a PR diff is defused, so the source can't end the untrusted block and speak outside it. An attachment read from its temp folder counts as untrusted too.
Changed
- **SupportCandy setup keeps the API out of the page cache.** A caching plugin with REST caching on (LiteSpeed Cache ships it on, for a week) saves the answers to the agent's API reads and serves them to anyone requesting the same address, login or not, because the application password travels in a header rather than a cookie. Reads go stale, and the ticket list is readable without a login. The Helpdesk walk now has a step to turn REST caching off or exclude `/wp-json/supportcandy/`, then purge.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | optional | only in a home with the Helpdesk pack that grants `helpdesk_note`: add `mcp__plugin_agent-kevin_kevin__helpdesk_assign` to `permissions.allow` in `.claude/settings.json`. |
manual | optional | on each SupportCandy site a connection reads: if it runs a caching plugin, turn off REST API caching (LiteSpeed Cache β Cache β Cache REST API) or exclude `/wp-json/supportcandy/` from the cache, then purge it. To check, request the ticket list without a login: a `200` answer means the cache is serving it; a `401` means it's protected. |
v0.8.62026-10-22
Added
- **Hand off a task to a GitHub issue.** `/project handoff <id>` (or "hand off <task>") moves a task's work to the team as an issue on the project's repo, named by `issues_repo` (and optional `issue_labels`) in the project README's frontmatter. It looks for a matching open issue first, drafts the issue with nothing from the home in it (no Thread, no home paths), and opens it only on a yes to that draft. The task stays open and records the issue's URL in a new `issue` field (`task_update`, `task update --issue=`), shown as `β owner/repo#N` in TASKS.md and in the dashboard's task details.
- **Sync offers to close a handed-off task once its issue closes.** It lists each repo's open issues once, checks only the missing ones, and shows a closed one as a `β Handed off` line, with the close offered in the closing interview (done for completed, cancelled for not planned). Sync never closes a task itself, and a repo it can't read says so, never "still open".
- **An accepted issue moves to `in progress` when work starts.** Before the first edit on work that starts from an `accepted` issue on a helpdesk queue's repo, the engineer skill offers to swap that label for `in progress`.
- **`/helpdesk reviews [slug]` turns App Store bug reports into one card each.** It reads the reviews since the last complete read at every rating (a 5β review can report a bug), clusters them by break, and gathers each bug's open and closed cards, tickets (`helpdesk_tickets` search), older reviews and planned tasks. Then it offers a card that carries them all, or a comment on the card already open. The pulse sends its review patterns through the same steps.
- **Sync counts App Store reviews.** Each queue profile with an App Store app gets a `Reviews, last 24h` line with every star bucket under its ticket counts. New reviews since the last read offer `/helpdesk reviews <slug>`. Both reads pass `limit: 0`, which `appstore_reviews` now accepts: counts and coverage only, no review text.
- **A finished fix gets the release it ships in.** Once a fix that started from an `accepted` issue is proven, the engineer skill offers to set the issue's milestone to that version and drop `in progress`, and writes `Fixes #<n>` in the commit message or PR description, so GitHub closes the issue as completed when it lands. A closed issue with an unreleased milestone is fixed but not shipped; the helpdesk pulse drafts the "it's fixed" replies once that version is live. Nothing in the plugin closes an issue itself. These steps and the `in progress` one apply only to issues on a repo a helpdesk queue's `## Raising` names; issues on any other repo are left to whoever runs them.
- **The agent can open a pull request, and it always asks first.** `github_pr_create` opens a PR from a pushed branch (`head`, optional `base` and `draft`) on the repo owner's token, which needs Pull requests Read and write. No pack grants it: init's baseline `permissions.ask` lists it, so every call stops for the operator in every mode, auto included.
- **The agent can fix its own GitHub comment.** `github_comment_update` replaces the text of a comment on an issue or a pull request's conversation, by the id after `#issuecomment-` in its URL. It edits only a comment the token's own account wrote: a repo owner's token could edit anyone's, so the tool checks the author first and refuses someone else's. Inline review comments aren't covered.
Fixed
- **`task_close` closes a blocked task.** A blocked task went straight to `done`, which the status rules refuse, so closing it failed with "Invalid status transition". It now steps through `active` the way an open task does.
- **`github_pr_update` works on a classic `repo` token.** It ran `gh pr edit`, which first asks GitHub for org and team fields (`login`, `name`, `slug`) that a classic token can't read without `read:org`, so every edit failed on a scope the edit itself doesn't need. It now patches the title and body through GitHub's REST endpoint, which needs only `repo` (or Pull requests write on a fine-grained token).
- **A reviews read is incomplete when Apple's feed drops a storefront that has reviews.** The feed sometimes returns an empty first page for a storefront it served minutes earlier. `appstore_reviews` used to call such a read `complete` whenever any other storefront answered, so a pulse or reviews run could record its `reviews_through` past reviews it never saw. A storefront with reviews seen before that comes back blank now leaves the read incomplete and is named in the warnings.
- **A blank reviews page is asked again past Apple's cache.** The feed answers most requests with an empty page and its CDN keeps each URL's answer for minutes, so asking the same URL again changed nothing. A blank page is now asked again with a random `nonce` that reaches Apple's server: once for any storefront, and three times, four seconds apart, where reviews were seen before. The `?cc=` second address is gone.
Changed
- **Ask-only tools refuse to run without their ask rule, and Codex asks for them too.** `curl_run`, `seed_import` and `github_pr_create` are marked ask-only: the server refuses a call while the home's `permissions.ask` lacks the tool, because `/plugin update` loads new tools before `/agent-kevin:upgrade` adds their rule and auto mode would approve them unseen in between. A home that removed `curl_run` or `seed_import` from `permissions.ask` now gets an error naming the rule to restore. In a Codex home, every MCP tool `permissions.ask` names, the agent's own and a mirrored server's such as Xcode's `InvokeDebuggerCommand`, gets `approval_mode = "prompt"` in `.codex/config.toml`, so Codex asks before each call as Claude Code does. A per-tool approval you set in Codex ("Always allow") stays for every other tool, where before it stopped the next regeneration with an error.
- **The Xcode pack grants `DocumentationSearch` by name.** `/agent-kevin:configure-skills` adds `mcp__xcode__DocumentationSearch` to `permissions.allow` beside `mcp__xcode__*`, so Apple's documentation lookup keeps its grant if the glob is narrowed, and deconfigure revokes both.
- **A bare `/engineer simplify` reviews this session's changes and fixes them.** With no target it takes the uncommitted diff plus this session's commits, re-reads the final files, runs the build, the full test suite and a caller check, and fixes the clear findings before reporting, holding judgment calls for the operator. Code the session didn't write still gets findings first and waits for a pick.
- **The GitHub pack's token steps name the classic-token fallback.** An org that holds fine-grained tokens for approval gets a classic token under that owner's key instead (`repo`, `read:org`, `read:user`, `user:email`, with an expiry date), which reaches every repo the account can.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add `mcp__plugin_agent-kevin_kevin__github_pr_create` to `permissions.ask` in `.claude/settings.json`, in every home (the tool is gated even where the GitHub pack is off). |
settings | optional | only in a home with the Xcode pack: add `mcp__xcode__DocumentationSearch` to `permissions.allow` in `.claude/settings.json`. |
settings | optional | only in a home with the GitHub pack: add `mcp__plugin_agent-kevin_kevin__github_comment_update` to `permissions.allow` in `.claude/settings.json`. |
v0.8.52026-10-22
Changed
- **Helpdesk raises a ticket as a bug, a feature or a task.** `/agent-kevin:helpdesk raise <id>` (or "raise 318") proposes the kind with a one-line reason, then files it wherever the queue profile sends that kind: a task of the matching type (`bug`, `idea`, `task`) or a GitHub card, after the same duplicate check and with the ticket in the title, so the pulse still drafts the reply when it closes. `/agent-kevin:helpdesk bug <id>` stays as the shortcut for a bug. A profile's `## Filing bugs` section is now `## Raising`, with a destination per kind; a kind it doesn't name goes where bugs go, and one it sends nowhere is never raised. The pulse lists the tickets to raise with their kind.
- **`database_query` checks a secret column with aggregates only.** The tool's description now says a key, token or password column is checked with `count`, a null-count filter or `min(length(β¦))`, never selected, grouped by or cut with `substring`, so its values never reach the transcript.
Fixed
- **SupportCandy status reads reach old tickets.** A ticket list filtered by status read only the 1,000 most recently updated tickets across every status, so older open tickets never reached the pulse, a profile's routines or the queue counts. The list now reads 500 tickets a page, so the same 20 requests reach 10,000.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | Platform's scratch-files paragraph is shorter, says nothing may follow the X's in a `mktemp` template (macOS keeps a suffix literal), and keeps the printed path in a variable inside the same command that uses it. Workflow's verify-before-claim line says a claim about this machine's state is checked in the same turn as the claim. |
manual | optional | Xcode pack homes only: `.claude/rules/xcode.md` gains the Ground rules bullet "Set the run destination after every scheme switch" after "Compiles is not verified". Add it by hand; homes without the pack skip this. |
manual | optional | in a home with a queue profile (`projects/<slug>/helpdesk.md`), rename its `## Filing bugs` section to `## Raising`, and say there where feature requests and tasks go when they shouldn't follow bugs. The skill no longer reads the old heading. |
v0.8.42026-10-21
Added
- **helpdesk skill.** Works a project's support queue through the Helpdesk pack: a pulse (open tickets ranked, patterns, bug candidates, saved to `reports/helpdesk/`), a ticket deep-dive, an account view, a drafted reply left as a private note once approved, and bug filing into a task or a GitHub card (repro, log excerpt, screenshots, never the customer's contact details) after a duplicate check. The pulse closes the loop: it drafts questions from cards waiting on the user and offers replies for cards fixed or declined since the last pulse. Every write (a note, a card, a comment, an answer added to a task) is shown and waits for a yes, and the skill pre-grants no write tool, so the home's permissions decide what it may write.
- **Queue profiles.** A project's `projects/<slug>/helpdesk.md` is its queue's own workflow, written by `/agent-kevin:helpdesk setup <slug>` (or "set up helpdesk for <project>") in six rounds (queue, pulse, bugs, replies, context, routines): its connection, which statuses count as open, reply rules and context, a pulse and bug lifecycle that extend or replace the plugin's defaults, and routines of its own run as `/agent-kevin:helpdesk <routine> <slug>`. Setup checks access first and runs the configure-skills walk when there's no connection it can read. Sync nudges each routine in the profile's `schedule` (`pulse:daily`, `digest:weekly`) when its newest report falls before the current day, week or month; it never runs one. Seed bundles carry a project's profile.
- **Named helpdesk connections.** One SupportCandy site or Pylon workspace per connection. The configure-skills walk asks which project each one is for: a project's connection is named after it and carries that name as a key suffix (`SUPPORTCANDY_URL_<NAME>`, `PYLON_API_TOKEN_<NAME>`), and **No project** is the default on the plain keys. A named connection reads only its own keys and never falls back to the default. `helpdesk_connections` lists what is configured without a credential, every helpdesk tool takes `connection`, and suffixed secrets are masked in logs like the plain ones.
- **More helpdesk reads.** `helpdesk_accounts` lists Pylon accounts; `helpdesk_lookups` lists SupportCandy statuses and categories and Pylon tags, teammates and macros. `helpdesk_tickets` takes `since: 'any'` and, on Pylon, tag, assignee and account filters (a helpdesk that can't apply a filter refuses it), up to 1000 tickets, and says `more` when it stopped at the limit, so the pulse shows the queue as `<N>+ open`. `helpdesk_ticket` adds a Pylon issue's opening body, linked engineering issues and CSAT.
- **Queue counts.** `helpdesk_stats` counts a queue's tickets updated in a window (default 24 hours) by status, tag, unassigned and newly opened: numbers only, never ticket text. `/agent-kevin:helpdesk stats` shows them, and sync's Support block counts every queue: each project's profile, then each connection no profile reads, the no-project default included (Pylon by its open statuses, SupportCandy across every status).
- **App Store pack.** `appstore_reviews` reads any app's App Store reviews by link or id from Apple's public feed (no key, read-only, never replies), learns which country storefronts an app's reviews come from (`.state/appstore/<id>.json`), and reports what it read: a blank feed gives no count, never zero. A queue profile can name its app, and the pulse then reads the reviews since the last complete read and files review bugs without a reply.
- **Stacked PR reviews.** The engineer skill reviews a stack from its edge PR in one report: each finding names its layer, is read at that layer's head and anchored in its diff, and the page badges and filters findings and threads by PR. The summary comment becomes a stack overview (blockers, earlier threads, before/after diagrams, target layout, code skeleton). `--layer` keeps the single-layer review.
- **Paste boxes show the rendered comment.** Every paste box on a PR report opens on its markdown as GitHub renders it (Mermaid drawn), with a Raw toggle; Copy still copies the exact text.
Changed
- **Helpdesk tickets carry their people.** The requester, assignee and each message's author come back with name and email where the helpdesk gives them, so the agent can find the account and answer by name; nothing written to GitHub carries a customer's name, email or account.
- Multi-step review comments are numbered one-fact steps with `file:line`, an outcome and the fix; the PR report warns on a paste paragraph over 60 words and on a thread given two pastes.
Fixed
- **A SupportCandy customer's own message came back tagged as an agent's**, and an assignee had no name: the ticket and thread endpoints send ids as numbers or strings, and they were compared as sent. Ids now match either way.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | upgrade's baseline reconcile adds `Skill(agent-kevin:helpdesk)` to `permissions.allow` when the home hasn't placed it in allow, ask or deny. Applied automatically. |
template/AGENTS.md | mandatory | the reports routing row and the layout tree gain `reports/helpdesk/` and a project's optional `helpdesk.md` queue profile. |
settings | optional | only in a home with the Helpdesk pack: add `mcp__plugin_agent-kevin_kevin__helpdesk_connections`, `mcp__plugin_agent-kevin_kevin__helpdesk_accounts`, `mcp__plugin_agent-kevin_kevin__helpdesk_lookups` and `mcp__plugin_agent-kevin_kevin__helpdesk_stats` to `permissions.allow`. Skip and each asks on first use. |
manual | optional | to read App Store reviews, run `/agent-kevin:configure-skills` β App Store. To work a project's support queue, run `/agent-kevin:helpdesk setup <slug>` or say "set up helpdesk for <project>". |
v0.8.32026-10-21
Added
- **A token per GitHub owner.** A fine-grained token reaches one owner's repos only, so the GitHub tools now pick `GITHUB_TOKEN_<OWNER>` (the owner's login uppercased, hyphens as underscores) for the repo each call names, then the catch-all `GITHUB_TOKEN`, then the operator's `gh auth login`. A `gh` or `git` child sees only the token picked for that call, every `GITHUB_TOKEN*` value is masked in the log, and `github_fast_forward` reports `NOT_CONFIGURED` per repo when its owner has no token.
- **GitHub writes, decided by the token.** `github_issue_create`, `github_issue_comment` (both attach screenshots and videos with `gh` 2.99+), `github_issue_update` (title, description, labels, milestone) and `github_pr_update` (a PR's title or description) run on the same per-owner token as the reads, so the token's permissions decide what they may do: Issues or Pull requests Read and write. Attaching needs the Write role on the repo, not Contents write on the token. Nothing merges, closes, re-runs a workflow or edits someone else's comment.
- **Your own PR's description, applied after you approve it.** The engineer skill's PR playbooks still post nothing, with one exception: the walkthrough's Describe gap and the replies hand-back offer to apply a new title or description to the operator's own PR with `github_pr_update`, after showing the current and proposed text. A teammate's PR is never edited.
- **Helpdesk pack.** `helpdesk_tickets`, `helpdesk_ticket`, `helpdesk_attachment` and `helpdesk_note` read support tickets and leave private draft notes in SupportCandy or Pylon through one ticket shape that never carries a requester's name or email. The note is the only write, so a person sends every reply. `helpdesk_attachment` saves a ticket's log or screenshot to a temp folder outside the home, ready for a GitHub issue.
- **guide skill.** Writes a guide someone else can follow as one self-contained HTML page (a setup walkthrough, onboarding, or a shared workflow and who does what) from a house template with a sidebar, tickable steps, copyable commands, zoomable screenshots and a swimlane.
- **Task tools set more fields.** `task_create` takes `parent` and `checklist`, and `task_update` takes `parent`, `depends_on` and `description` (replacing only the Description section) and answers with the fields it wrote, so a field a stale server dropped shows in the reply.
- **Copy a diagram's Mermaid source** from the expanded diagram view, and a **back-to-top button** on long themed pages (PR reviews, explainers, the roadmap).
Changed
- **The GitHub pack is one walk.** It grants all fifteen tools, lists the owners behind the configured checkouts with the key name for each, and denies `gh` in the agent's own shell (`Bash(gh)`, `Bash(gh *)`), so GitHub is reached only through the tools, under the token picked for each repo.
- **Codex gets the home's shell denies.** `.codex/rules/kevin.rules` turns each `Bash(β¦)` entry in `permissions.deny` into a `forbidden` rule beside the prompt rules from `permissions.ask`; Codex applies the strictest match, so `gh pr create` is forbidden too.
- **GitHub errors say what to fix.** A rejected token (expired, revoked or mistyped), a missing permission, a repo the token can't see, and an owner with no key each get a message naming the key and the fix.
- The engineer PR report's before/after card reads "Before and after: what changes when this merges" and names the PR's own base branch instead of always saying `main`, and the proposed description's copy box is labelled "Markdown for the PR body".
Fixed
- `helpdesk_tickets` with a status filter on SupportCandy filters while paging, so a filtered list no longer comes back short while matching tickets remain in the window.
- **Seed bundles carry a pack's denies.** A home set up from a seed now gets the GitHub pack's `gh` block along with its tools; before, only `allow` and `ask` entries travelled, so the block waited for the GitHub walk to run again.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | upgrade's baseline reconcile adds `Skill(agent-kevin:guide)` to `permissions.allow` when the home hasn't placed it in allow, ask or deny. Applied automatically. |
settings | optional | only in a home with the GitHub pack: add `mcp__plugin_agent-kevin_kevin__github_issue_create`, `mcp__plugin_agent-kevin_kevin__github_issue_comment`, `mcp__plugin_agent-kevin_kevin__github_issue_update` and `mcp__plugin_agent-kevin_kevin__github_pr_update` to `permissions.allow`, and `Bash(gh)` and `Bash(gh *)` to `permissions.deny`, so GitHub goes through the tools. A home wired for Codex picks the deny up as a `forbidden` rule when the upgrade regenerates its rules. Skip if you want the GitHub pack read-only. |
manual | optional | repos under more than one GitHub owner: add one `GITHUB_TOKEN_<OWNER>=` line per owner to `.state/secrets/.env` in your editor (`my-org` β `GITHUB_TOKEN_MY_ORG`), then restart. An existing `GITHUB_TOKEN` keeps working as the catch-all. For writes, give that owner's token Issues and/or Pull requests: Read and write. |
manual | optional | to read support tickets, run `/agent-kevin:configure-skills` β Helpdesk (SupportCandy or Pylon). |
v0.8.22026-10-19
Fixed
- **Sync commits the `assets/` and `scripts/` home folders.** The brain commit only knew the folders that existed before 0.8.1, so the upgrade that moved the avatar out of `.claude/assets/` left history with the old file deleted and `assets/` untracked. Both folders now commit beside `.claude/`, so a move out of it lands as one rename, and a flow's `.env` under `scripts/` still never enters history. A home that already synced on 0.8.1 gets `assets/` committed on its next sync.
β¬ Upgrade
None β code-only, no bun install or HOME changes.
v0.8.12026-10-19
Added
- **Pin reports and docs to a project.** A project's README can hold a `## Pinned` section, in the
- **A renamed agent knows its former names.** IDENTITY.md's `- **Formerly:**` field lists the old
- **Expand and zoom any diagram on a generated page.** Review and explainer pages give every drawn
Changed
- **`.claude/` keeps only what Claude Code reads.** The agent's avatar moves to `assets/`, and the
- **The rename-agent skill is a script with a dry run.** It shows every line it would change before
- **The engineer PR review page was reworked.** The page checks the PR description's claims, shows
- **IDENTITY.md says the agent runs in whichever agent CLI launched it**, not Claude Code, so a
Fixed
- **Rename-agent never writes through a symlinked file or folder.** It also writes exactly what the
- **Capture skips the API-request records** that Claude Code 2.1.300 logs in transcripts, so they no
- **find-session leaves logged API requests out of the hit count**, so a term from the injected
- **`/queue` ignores subagent and teammate turns** (Claude Code 2.1.299+). Before, a background
- **`setup_worktree` copies only local files the new checkout doesn't track**, so a tracked
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.8.1.ts. It moves `.claude/assets/*` to `assets/` and `.claude/browser-flows/<flow>` to `scripts/browser/<flow>` (the flow's `.env` with it), then repoints the `IDENTITY.md` links of the files that moved. An identical copy already at the destination drops the old one; a differing one stays in both places and is reported, and its link is left as it was. OS litter files (`.DS_Store`) neither block a dedupe nor keep an old folder alive. Idempotent. |
template/AGENTS.md | mandatory | the folder tree: `.claude/` holds only what Claude Code reads, and `assets/` and `scripts/browser/<flow>/` sit at the home root. |
template/IDENTITY.md | optional | the Short Bio says the agent runs inside whichever agent CLI launched it (Claude Code, Codex, or another). |
manual | none | the upgrade never reconciles IDENTITY.md's `## Who` block. In that block, change `- **Kind:** AI assistant (Claude Code plugin)` to `- **Kind:** AI assistant (agent CLI plugin)`. |
manual | none | only if one of your own flows or scripts names `.claude/browser-flows/` or `.claude/assets/` by path: point it at `scripts/browser/` or `assets/`. Flows that import `lib/flow` need no change. |
manual | none | only if you hold a seed bundle exported before 0.8.1: it no longer imports, so re-export it from the source home once that home is upgraded. |
v0.8.02026-10-15
Added
- **A seed bundle can carry browser flows.** `.claude/browser-flows/` is a seed root like custom
- **A seed bundle records who it is for.** The export asks whether the bundle is for your own second
Changed
- **Env keys use the shared `AGENT_*` names only.** A `KEVIN_*` key no longer overrides its `AGENT_*`
- **Codex wiring writes `AGENT_HOME` only**, reads the home's `AGENT_*` settings only, and removes the
- **Codex runs the MCP servers Claude Code runs**, not only the pack servers (which, like `xcode`,
- **The banner shows the agent's own name and emoji** from `IDENTITY.md` instead of `KEVIN π`, in
- **Briefings add the Hijri date only when you keep that calendar.** A faith mention alone (a team
- **A seed bundle exported under a new name is renamed.** `IDENTITY.md` and `SOUL.md` carry the new
- **Carried MCP entries no longer hold the source home's path.** A seed bundle's MCP entries hold a
- **A project-slice seed export pre-ticks the packs** the project's README and tasks show it uses.
- **A blocked task can go back to open** once it's unblocked, and the scan clears a leftover
Removed
- **Support for homes that never ran the 0.7.0 upgrade.** The plugin reads only `.state/`; the
Fixed
- **A seed import's confirm is never answered for you.** It is asked on its own with all three
- **The finished sync band wraps at whole pieces** in a narrow pane instead of breaking words.
- **Home recovery advice names the file that matters.** A home is the one whose `.state/version.json`
- **Codex setup keeps credentials out of `.codex/config.toml`.** The shell env it copies from the home's
- **The upgrade refreshes its template snapshot without `rm -rf`.** It deleted and recopied
- **`google_auth` says where its tokens live:** the home's secrets store (`.state/secrets/google/`).
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.8.0.ts. It renames `KEVIN_*` keys and `$KEVIN_*` references to their `AGENT_*` names in both `.claude/settings.json` and `.claude/settings.local.json` (env keys, and references in any string), `.state/secrets/.env` (key names, line by line, values, order and mode kept) and `.mcp.json` (references and server env keys; the configure-skills home fallback collapses to one `AGENT_HOME` read). Where both spellings are set in the same store, the `KEVIN_*` value wins, since it was the one in effect, and a shadowed secrets line is dropped (the backup keeps it); an `export KEVIN_X=` line, which the plugin's loader never read, is renamed for the server wrappers that source the file but displaces nothing. A `KEVIN_*` setting whose `AGENT_*` twin sits in the secrets file gives way to the secrets value, as every secret does. A file that doesn't parse is named in the error, never quoted. Every file is read before any is written, so one that doesn't parse stops the run with nothing changed. It also removes the pre-0.7.0 `.kevin/` guards: the exact secrets deny rules init and the 0.7.0 move wrote (in either settings file's `permissions` and `sandbox`) and the `.kevin` lines in `.gitignore`, with the old template's comment directly above them; your own rules that mention `.kevin` stay, and a home that still has a `.kevin/` folder keeps all of them. Config backups go under `.state/updates/`, the secrets backup stays in `.state/secrets/`. The report names keys and pruned rules, never values. |
template/AGENTS.md | mandatory | the manual names `AGENT_GIT_REPOS` and `$AGENT_CODE_PATH` instead of their `KEVIN_*` spellings, which nothing reads any more. |
manual | none | only if `KEVIN_*` keys are set outside the home (`~/.claude/settings.json`, which the upgrade checks and lists, or a shell profile): nothing reads them any more. Delete each, and put a per-home value (code path, repo list, DB connection) into each home's `.claude/settings.local.json` as `AGENT_*`. Only a value every home should share (timezone, log level) is renamed in place. A `KEVIN_HOME` pin (sessions started outside the home) becomes `AGENT_HOME` there only on a machine with a single agent home; otherwise delete it. |
manual | none | restart Claude Code (and Codex) after the upgrade: a running session keeps the old names until it relaunches. |
manual | none | only for a home whose data is still in `.kevin/` (it never ran the 0.7.0 upgrade): this version no longer reads or moves that folder. Install v0.7.3 (a local checkout at tag `v0.7.3`), run `/agent-kevin:upgrade` there, then update to this version. |
v0.7.32026-10-14
Added
- **`/reports`** (Claude Code mod) shows the reports this conversation produced in a row above the
- **`/session`** (Claude Code mod) shows this conversation's session id in a row above the prompt,
Changed
- **`/today` shows its agenda in a row above the prompt** with a Dismiss button, the same way
Removed
- **The manual no longer asks for bare markdown paths in chat.** The rule worked around a terminal
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | the Platform section drops the "Paths in chat are bare when the terminal opens them" paragraph. |
v0.7.22026-10-12
Added
- **`/queue <prompt>`** (Claude Code mod) holds a prompt until the current task ends, then sends
- **PR reviews and replies end in one page** with a Copy button on every finding, question, nit,
- **Two new review lanes.** `generated-code` covers what fast, often model-written code gets wrong
- **Reviews add a reading guide and a case against merging.** A review now names the hunks worth
- `github_pr_view` returns `headRefOid`, `isCrossRepository` and `mergeCommit`, so a review can
- **Every generated page has an Auto / Light / Dark switch, Auto by default.** The dashboard,
- **Explainers have a template.** The engineer skill writes only an explainer's body; a script
- **`/done` suggests the task to close.** After `/done `, a letter of the id or a word of the title
- **A new folder points at setup.** In a folder that isn't an agent home yet, a row above the
- **Pin reports to the dashboard sidebar.** List them in `reports/pinned.md`, one markdown link
- **Pins and surfaces reach the agent.** Every session's context lists the pinned reports. The
- **The Reports page leads with the pins** as their own group, with a π Pinned filter chip beside
- **Pick a project's color.** `hue:` (0β359) in a project README's frontmatter colors its card,
Changed
- **A project card shows its Roadmap and Focus links on its first line**, so they're visible
- **The Brain page's Injected at SessionStart list** leads with today's date and shows each
- The README installs the plugin with one command, `/plugin install agent-kevin --marketplace <repo>`,
- **Sync's `sync_stats` tool sits in the prompt's tool list** instead of behind tool search, so
- Claude Code 2.1.293 or newer is required (mod autocomplete and tools kept out of tool search):
- **Review depth follows risk.** A PR under 300 changed lines with no risk-triaged file runs
- Lanes carry slugs, and findings are routed by evidence. A real defect that was already there
- PR replies answer every part of a reviewer's question, quote each comment's opening words so a
- The engineer skill may call `github_pr_checks` and `github_run_log` without a prompt, to read a
- The mermaid validator exports `parseMermaid`, and its failure line now carries Mermaid's
- **The Xcode pack stops asking before `RunCodeSnippet`.** Snippets run Swift outside the
- **The `guard` hook enforces the two shell rules a written rule couldn't hold.** Under Claude
Removed
- The markdown review and replies templates. The page and its card replace them, and
Fixed
- A post-merge PR audit can find its code after the head branch is deleted: it reads the PR's
- `browser_screenshot` and `browser_pdf` of an explainer or PR page capture its diagrams drawn,
- On a busy day, the session context's list of today's reports is cut at the last whole entry,
- **The sync band follows a sync handed to a background agent.** It used to show the run done
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.7.2.ts. It drops `mcp__xcode__RunCodeSnippet` from `permissions.ask` in `.claude/settings.json` (the settings merge only adds, so the removal lives here); `mcp__xcode__InvokeDebuggerCommand` and every other entry keep their place. A home without the Xcode pack is untouched. |
template/AGENTS.md | mandatory | Platform's shell-commands paragraph replaces "every git or build call starts with its own absolute `cd`" with `git -C`, absolute paths or a subshell `cd`, and keeps the absolute `cd` for commands handed to the operator. The scratch-files paragraph gains the exact-printed-name rule and names the `guard` hook, and its `mktemp` form gains a `/tmp` fallback for a Git Bash without `TMPDIR`. Context Loading's dynamic list gains today's and pinned reports. |
template/CLAUDE.md | mandatory | the bridge's SessionStart sentence names today's and pinned reports. |
v0.7.12026-10-08
Added
- **Notices.** Upgrade and sync nudges come from one place every surface reads. Each carries a
- **Sync offers a north-star roadmap** at its close while the home has no `roadmap.html`. A
- **The dashboard's Capabilities page has a Mods tab**: each mod feature with the commands and
Changed
- The plugin's name, its MCP server key and the CLI path are derived from the manifest instead of
Fixed
- The status line reads on a light terminal. The model name, folder and branch were drawn in white
β¬ Upgrade
None β code-only, no bun install or HOME changes.
v0.7.02026-10-08
Added
- **Mods (Claude Code).** The plugin loads one hooks module, `mods/hooks/register.ts`, beside its
Changed
- **The data dir is `.state/` for every agent.** `.kevin/` becomes `.state/`, and its
- **The `.state/secrets` guard is always written** to the home's own settings, including homes whose
- **init stops in a home still on `.kevin/`** and points to the upgrade, instead of scaffolding a
- **Session start flags a `.kevin/` that reappears beside `.state/`**: a session still on the older
- **Sync's closing "what next" question takes several picks.** Act now works through them in order;
- Claude Code 2.1.287 or newer is required (mods): init and upgrade stop below it with
Fixed
- The log file is resolved on each write, so a long-running server stops writing to a folder that
- Knowledge lint resolves links to archived tasks. The flywheel moves closed tasks to
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.7.0.ts (records the plugin in `.kevin/version.json`, adds the `.state/secrets` deny rules and the `.state/` gitignore rules, renames `.kevin/` to `.state/`, and repoints every `.kevin/` path in the machine-local config, `.mcp.json` and `.claude/settings.local.json` (a pack server's secrets file, or an env value, hook or permission you added); every rewritten file is backed up under `.state/updates/`, and a re-run finishes a move that stopped partway). |
template/AGENTS.md | mandatory | the Knowledge Structure tree names `.state/`. |
template/.gitignore | mandatory | the runtime rules name `.state/`; the 0.7.0 script and the baseline reconcile apply it. |
manual | none | close this agent's other sessions (Claude Code and Codex) before running the upgrade, and restart once it finishes. A session started on the older plugin stops recognising the home once the folder moves: its tools refuse and its transcript is not captured. |
manual | none | only if you created a `.state/` folder by hand: the move stops without changing anything. Move what you put there into `.kevin/`, move `.state/` aside, and run the upgrade again. |
v0.6.52026-10-07
Added
- **A home records which plugin owns it.** `.kevin/version.json` now carries `"plugin": "agent-kevin"`,
- **Paths in chat stay bare** in the manual template's Platform section: some terminals (cmux among
Changed
- **Skills spot an agent home by its data dir, not `SOUL.md`.** Upgrade and self-review now look for
Removed
- **The runtime-dir override** (`AGENT_RUNTIME_DIR` / `KEVIN_RUNTIME_DIR`). Only the server honoured
Fixed
- A deferred-capture test could read `index.json` instead of the day file when APFS listed it first.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | the Platform section drops "where SOUL.md lives" from the launch rule and gains the bare-paths-in-chat rule. |
manual | none | only if this home set `KEVIN_RUNTIME_DIR` or `AGENT_RUNTIME_DIR`: rename its data folder back to `.kevin` and delete the variable from settings, or the home is no longer recognised. Homes that never set it need nothing; the upgrade's `home-baseline.ts` run adds the `plugin` record on its own. |
v0.6.42026-10-07
Added
- **A monthly brain pass in self-review.** An inventory script finds decay: tasks untouched for 30
- **Sync offers the self-review when it's due**, first and on its own: Run it now, Tomorrow, or Skip
- **The flywheel reads sessions.** It catches up on the daily memory written since its last report,
- `/self-review help` prints the menu.
- **Upgrade brings the plugin itself current first.** A git-checkout install is fast-forwarded
- **init writes a concrete memory-index scaffold**, with the sections compile keeps, in its order.
Changed
- **Sync runs the flywheel skill's own protocol** with five sync-specific overrides, instead of a
- **Sync refreshes Open Questions whenever it compiles.** Only a manual compile used to, so a gap
- **Self-review is two playbooks**: brain (the data) and rules (the prompt surface).
- **Playbooks get the plugin root from their skill.** Claude Code fills `${CLAUDE_PLUGIN_ROOT}` only
- **Codex homes default to GPT-6.1 Sol** (high) instead of Astra.
- **Project create and archive edit the knowledge index's Projects row themselves.** Nothing
- Sync's Code and Dashboard lines use π» and π, which keep their space in a terminal.
- **Shipped defaults come from the operator.** The yearly plan weighs the personal commitments they
- **The manual gains two workflow rules:** once a branch has a PR, corrections land as forward
- init no longer suggests pinning the home in the shell rc: a pin is for a single-home machine.
- **SOUL asks for complete answers.** Every question the operator asked gets answered, each by name,
Fixed
- Database passwords pasted raw with URL-reserved characters connect.
- The briefings' "files touched today" check works where `find` is bfs, and the evening wrap before
- The morning brief signs with the agent's own emoji, and the CLI's `compile status` help lists
- Upgrade's steps run 4, 5, 6 again (the baseline stamp had lost its heading), init's storage
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/SOUL.md | optional | Writing Style gains one line: answer every question asked, by name, and hand decisions back with a plain explanation and a recommendation. |
template/AGENTS.md | mandatory | the Workflow section gains the PR forward-commit rule, the knowledge lifecycle gains the home-history line, and the tree lists `.obsidian/`. |
script | required | run skills/upgrade/scripts/0.6.4.ts (a Codex home still on `gpt-6-astra` moves to `gpt-6.1-sol`, once; any other model, and homes without Codex, are left as they are). |
manual | none | sync will offer a monthly self-review (brain, then rules); a home never reviewed is offered one once its oldest session is a month old. |
v0.6.32026-10-02
Added
- **The session banner nudges a sync.** Once three days pass since the last sync, the banner adds
Changed
- **Sync records itself.** Sync's final dashboard call passes `sync: true`, which stamps the run
- **Adversarial review on code leads with design.** The reviewer applies the engineer skill's
Fixed
- Plan-spec specs are written through `report_write`, so they appear in `reports/index.md` and the
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/IDENTITY.md | optional | the Operational Pattern "Review loop" line now says the agent fixes what's worth the code, simpler shape first, and offers the edge cases it deferred. |
v0.6.22026-10-01
Added
- **The media skill.** Hand over a local recording (a screen recording, a ticket's video, a
- **`media_transcribe` tool.** It transcribes speech on the device, with nothing uploaded, using
- **`video_frames` grabs chosen moments.** A new `at` mode takes one frame at each second you give
- **Focus organize.** "I'm overwhelmed" now starts with a brain dump in plain chat and sorts it
- **Compile reads folders, zips and PDFs from the inbox.** Folders are walked at any depth and
Changed
- **Standup replies with a glance card.** The chat reply is one short card to read mid-standup,
- **Skill output signs with the agent's own emoji** from `IDENTITY.md`, not the default π. This
Fixed
- Browser captures and video frames stay inside `reports/captures`. Before this, a `name` like
- Frame labels round down, so 59.6s prints as `00:59`, not `00:60`.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | upgrade's baseline reconcile adds `mcp__plugin_agent-kevin_kevin__media_transcribe` and `Skill(agent-kevin:media)` to `permissions.allow` when the home hasn't placed them in allow, ask or deny. Applied automatically. |
manual | optional | to transcribe recordings, install `yap` from a normal terminal: `brew install yap` (macOS 26+). For screenshots from video, also install `ffmpeg` (`brew install ffmpeg`). Without them, the media tools say what is missing and stop. |
v0.6.12026-09-30
Added
- **Daily goals.** `/goals day` sets one to three outcomes for today and the evening wrap scores
- **A welcome after init.** Init can't ask what to do first, since the plugin only loads after a
- **Postman adapter for api-collections.** Postman v12's Native Git mode reads v3 YAML
- **Plans reviewed against their code.** adversarial-review resolves a plan's grounding (the repos
Changed
- **Fifteen skills fold into five playbook skills**, the same shape as engineer, focus and tax, so
- Sync's closing interview can run a due goals cadence itself (the week as `goals week interview`)
- Every skill is model-invocable except init, release and rename-agent, which also ship
- **Machine-bound settings live in `settings.local.json`.** A home's `settings.json` travels
- The roadmap skill reads init's goals draft (`knowledge/concepts/roadmap-draft.md`) for the north
- Codex homes default to `gpt-6-astra` at `high` reasoning: init and upgrade fill the home-level
- Marketplace add commands take `owner/repo`; the `github:` prefix Claude Code doesn't recognise
Removed
- The `morning-briefing`, `evening-briefing`, `quick-pulse`, `weekly-goals`, `monthly-goals`,
- Init no longer writes an absolute `plansDirectory` (Claude Code ignores a plans folder outside
Fixed
- Custom-folder rules an older init wrote as `Read(/abs/**)` never matched, since a single leading
- An evening wrap after midnight covers the day being wrapped from 00:00 until now, reading both
- The session radar dropped a session that was only slash commands (an `/upgrade`, a `/release`),
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.6.1.ts. It rewrites each retired `Skill(agent-kevin:<old>)` rule in `permissions.allow`, `ask` or `deny` of `.claude/settings.json` and `.claude/settings.local.json` to its successor's, in the same list (a gated `seed-import` still gates `seed`; a prefix rule like `Skill(agent-kevin:seed- *)` keeps working through exact successor rules). It moves the `weekly-goals` / `monthly-goals` / `yearly-goals` cadence keys to `goals-week` / `goals-month` / `goals-year`, rewords the goals placeholders in TASKS.md and adds a Daily Goals one, and reports (never edits) files you own that still name an old command. It rewrites `.claude/settings.json`, `.claude/settings.local.json`, `.kevin/cadence.json` and `projects/TASKS.md`; back those up first. It also moves this machine's entries (a status line that runs a program by absolute path, this plugin's `enabledPlugins` entry and the marketplace it names, absolute folder grants) from `settings.json` to `settings.local.json`; other plugins and marketplaces stay shared, writing the local file first, and rewrites `Read(/abs/**)` folder rules to `//abs`. Settings files keep their layout. |
settings | mandatory | upgrade's baseline reconcile adds the new skills' grants (`Skill(agent-kevin:briefing)`, `Skill(agent-kevin:goals)`, `Skill(agent-kevin:seo)`, `Skill(agent-kevin:seed)`, `Skill(agent-kevin:project)`) and the grants for skills that became model-invocable, when the home hasn't placed them in allow, ask or deny. Applied automatically. |
settings | mandatory | the Codex wiring regenerates and fills a missing home-level `model` / `model_reasoning_effort` in `.codex/config.toml` with `gpt-6-astra` / `high`; a value already set is kept. Applied automatically for homes wired to Codex. |
template/AGENTS.md | mandatory | the tree comments for `.claude/settings.json` (shared policy) and `.claude/settings.local.json` (this machine's plugin registration, status line, folder grants, env) follow the new ownership split. |
manual | none | the fifteen retired commands are now playbooks: `/briefing morning|evening|pulse`, `/goals week|month|year` (weekly-goals' interview is `/goals week interview`), `/seo audit|console|speed|serp|rank`, `/seed export|import`, `/project create|archive`, and `/focus week` is `/goals week`. Plain asks ("brief me", "plan the week", "run the SEO audit") route on their own. A schedule or script outside the home that runs an old command (`~/.claude/scheduled_tasks.json`, a cron or launchd job) needs the new one; the script only sees files inside the home. |
v0.6.02026-09-29
Added
- **Init asks about your world.** A new step (5d) asks what you're working on, what should land
- **Python runs through uv.** The manual's Toolchain section routes Python scripts through
- **Focus playbooks.** The focus skill is a router: refresh, add, plan, week, standup,
Changed
- **Focus is the day.** The dashboard's Today tab opens on a Focus view: today's three,
- **`standup` and `where-am-i` fold into the `focus` skill** as playbooks, next to new `week`,
- Every dashboard page header carries stat tiles, compacted to one line with a caption; each
- Sync pulls the focus queue on every run, and `report_write` re-renders the dashboard so a new
- The MCP server moves from `@modelcontextprotocol/sdk` 1.29 to the v2 TypeScript SDK
- The Codex starter prompts offer `$focus` instead of `$standup`.
- Claude Code's Haiku tier (its small background calls) runs on Sonnet 5.5: init always writes
- Claude Code 2.1.284 or newer is required, the release Sonnet 5.5 behind the Haiku-tier remap was
- Upgrade re-checks init's core deny list and sandbox block on every run, with the same test init
- Init checks that the plugin's packages are installed before it asks anything, and stops with
- The Perplexity key is optional. Without `PERPLEXITY_API_KEY`, the morning brief (and the sync
Removed
- The `standup` and `where-am-i` skills, now `/focus standup` and `/focus where-am-i`. Reports
- The standalone `<HOME>/focus.html` and its sidebar row.
Fixed
- Focus: a roadmap that names no task ids no longer flags every milestone as missing a task, an
- The dashboard reads goals without their list markers, so a numbered Weekly Goals block no
- The status line's context bar fills at least one cell for any usage above zero.
- A double-quoted task list item with escaped characters (`\t`, `\n`) is decoded like a scalar.
- Tax: coverage prices only an unbroken run of closes, a payslip is missing only after payday, a
β¬ Upgrade
| change | level | detail |
|---|---|---|
deps | required | `@modelcontextprotocol/server` replaces `@modelcontextprotocol/sdk`; run bun install in mcp-server. |
script | required | run skills/upgrade/scripts/0.6.0.ts (removes the generated home `focus.html`, which the dashboard's Today β Focus view replaces). A `focus.html` without the `focus-data` block is hand-made and is left in place; the report names it. Project focus pages are untouched. It also drops the dead `Skill(agent-kevin:standup)` and `Skill(agent-kevin:where-am-i)` grants from `.claude/settings.json` `permissions.allow` (the settings merge only adds, so the removal lives here); every other entry keeps its place. |
settings | mandatory | upgrade's baseline reconcile sets `env.ANTHROPIC_DEFAULT_HAIKU_MODEL` to `claude-sonnet-5-5` in `.claude/settings.json` when the home has none or still has `claude-sonnet-4-6`; any other model the operator chose is kept. Applied automatically. |
settings | mandatory | upgrade's baseline reconcile adds the Python guard (`Bash(pip install*)` and its variants) to `permissions.deny`, and `~/.cache/uv` plus `pypi.org` and `files.pythonhosted.org` to the project `sandbox`, when the home lacks them; an entry the operator already placed in allow or ask is kept as theirs. Applied automatically. |
settings | mandatory | the same reconcile writes init's core deny list into `permissions.deny` when the user settings have no deny list, and init's sandbox block into the project `sandbox` when neither the user settings enable the sandbox nor the project sets `sandbox.enabled` (skipped on native Windows). Existing values win and lists union. Applied automatically. |
template/AGENTS.md | mandatory | the memory-routing row and the `reports/radar/` tree comment name the focus skill's standup and where-am-i playbooks instead of the retired skills, and Toolchain gains the Python line (`uv run --with`, never pip). |
manual | none | `/agent-kevin:standup` is now `/agent-kevin:focus standup`, and `/agent-kevin:where-am-i` is `/agent-kevin:focus where-am-i`. Plain asks ("standup is coming up", "where am I") route there on their own. |
v0.5.32026-09-29
Added
- **`tax` skill.** Bookkeeping and tax compliance for the operator's companies and personal
- **`focus` skill and `focus_write` tool.** `/focus` renders `<HOME>/focus.html` across every
- **Task horizons.** A task can carry the day, week, or month it is planned for (`2026-09-28`,
- `task_scan` gains a `dueSoon` bucket (open work due in the next 14 days), surfaced by sync,
- `github_pr_list` takes `author`, `reviewRequested` and `search` filters and returns
- A roadmap check script (`skills/roadmap/scripts/check.ts`) that every roadmap write ends with.
Changed
- **Roadmap data is inline JSON.** A roadmap page carries its data in a
- The morning brief's Today section is the focus page's Today lane. Standup takes Next from it
- Written frontmatter stays flat and valid YAML: `report_write` rejects nested values,
- The manual and the Xcode rule say a `sandbox.excludedCommands` entry matches only the bare
Fixed
- `bun test` from the repo root no longer writes fixture homes into the checkout; a root
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run skills/upgrade/scripts/0.5.3.ts (moves each `roadmap.html` in the home and under `projects/<slug>/` to an inline `roadmap-data` JSON block). A page is replaced only when both versions render the same DOM with not one pixel different; any other page is left untouched and keeps working, and the report names it. Before/after screenshots stay under `.kevin/updates/roadmap-json-<stamp>/`. |
settings | mandatory | upgrade's baseline reconcile adds `mcp__plugin_agent-kevin_kevin__focus_write`, `Skill(agent-kevin:focus)` and `Skill(agent-kevin:tax)` to `permissions.allow`. Applied automatically; every addition is named in the report. |
template/AGENTS.md | mandatory | Conventions gains "Frontmatter values are flat"; Platform's sandbox paragraph gains one sentence on comparing a blocked command with the last run that worked. |
manual | optional | Xcode pack homes only: `.claude/rules/xcode.md` gains the bullet "An excluded command must be the whole command line" after the two shell exceptions. Add it by hand; homes without the pack skip this. |
manual | optional | tax deadlines: run `/agent-kevin:tax setup` to create an entity profile per company and for yourself; nothing is created until you do. |
v0.5.22026-09-28
Changed
- **PR work moves into the `engineer` skill.** `pr-review` and `pr-walkthrough` are retired as
- Review lanes gain three checks: a fallback that can re-send an instruction the first path may
- The init and templates wording, the dashboard cheatsheet, the reports category dot, the GitHub
- SOUL's Writing Style drops the em-dash rule.
Fixed
- The SessionStart banner shows the status-line warning only when no upgrade is due, instead of
- The secrets round-trip tests skip when a command sandbox refuses reads on a secrets store,
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | in `permissions.allow`, remove `Skill(agent-kevin:pr-review)` and `Skill(agent-kevin:pr-walkthrough)` if present; `Skill(agent-kevin:engineer)` covers PR work now. |
template/AGENTS.md | mandatory | the memory-routing row, the `reports/reviews/` tree comment, and "Where Your Code Lives" name the engineer PR playbooks instead of the retired skills. |
template/IDENTITY.md | optional | the Operational Pattern "Code" line names the engineer skill for all code work, including PR reviews, replies, and walkthroughs. |
template/SOUL.md | optional | Writing Style drops the em-dash rule. |
manual | none | `/agent-kevin:pr-review <n>` is now `/agent-kevin:engineer review <n>` (or `replies <n>` on your own PR), and `/agent-kevin:pr-walkthrough <n>` is `/agent-kevin:engineer walkthrough <n>`. Plain asks ("review 142", "walk me through my PR") route there on their own. |
v0.5.12026-09-26
Added
- **Home history.** The `home_history` tool and the `history` skill give a home local version
- **`/engineer simplify`** gets its own playbook, carrying the retired `simple-simplify` audit
Changed
- **Upgrade backfills init's baseline every run:** missing `.gitignore` rules, the
- **Worktree teardown.** `pr-review` removes the review worktree it created once the report is
Fixed
- `writeFileAtomic` writes to a unique temp file, so two writers of one file no longer share a
- Stuck home-history states from the pre-release review: a deleted history folder, a leftover
- The `history` skill runs setup on any home whose history is on, instead of stopping at status.
- Tower and other tools that open the history folder directly show the home's files instead of
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | upgrade's built-in baseline reconcile backfills `plansDirectory` and any missing init `permissions.allow` / `permissions.ask` entries, including the new `mcp__plugin_agent-kevin_kevin__home_history` and `Skill(agent-kevin:history)`. Applied automatically; every addition is named in the report. |
template/.gitignore | mandatory | ignore `.claude/settings.local.json*`, so a temp or backup copy of the local settings stays out of history; any other missing rule (incl. `!.kevin/knowledge.json`) is backfilled too. The baseline reconcile applies it. |
manual | optional | turn on version history for this home any time with `/agent-kevin:history`. Nothing is applied automatically; a history set up by hand is left as it is. |
v0.5.02026-09-23
Changed
- **Upgrade merges templates three ways.** A changed section is rebuilt as the new template plus
- The manual's "Verify before claim" asks for each finding in a multi-finding analysis to be
- SOUL's Writing Style splits the group-explanation clause into its own bullet (explanation, not
Fixed
- **Native Windows.** `template-drift.ts` reports the preferences facet as `knowledge/user/preferences.md` on every platform, and reads CRLF files line by line. The demo seeder, which needs a POSIX shell, now stops with a clear message on Windows instead of failing mid-render, and its test is skipped there.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | Workflow's "Verify before claim" line extended; three Code style / Code quality lines removed (section-aware three-way merge; operator lines and home-only sections untouched). |
template/SOUL.md | optional | Writing Style: one bullet split in two, two new bullets; an operator's edited copy is diffed first. |
v0.4.122026-09-23
Added
- **`engineer` skill.** A working method for code work in a repo: fix a bug, build a feature,
- **`self-review` measures a home against the templates every cycle.** `template-drift.ts`
- `demo-home.ts` seeds a fictional home and renders the public demo dashboard from it, with
- `skills.test.ts` parses every SKILL.md frontmatter, checks the name matches its folder, holds
Changed
- **Generic rules from real homes moved into the templates.** The manual gains Workflow lines
- The TypeScript rule is rewritten around types, narrowing, and boundary parsing plus house
- `preferences.md` holds personal tastes only. Working rules route through feedback into
- Review, spec, and writing skills carry the engineering principles.
- Links to the retired `dev.agentlayer.one` point at `agentlayer.one`.
Fixed
- Four skills shipped frontmatter a YAML parser rejects, and `where-am-i`'s description ran past
- Shipped files no longer carry a real operator's name, projects, or personal defaults; examples
Removed
- `simple-simplify`. Its audit criteria live in `engineer`'s refactoring playbook, which also
- The unused `templates/USER.md`; init writes USER.md from its own inline template.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | in `permissions.allow`, add `Skill(agent-kevin:engineer)` and remove `Skill(agent-kevin:simple-simplify)` if present. |
template/AGENTS.md | mandatory | new Workflow, Platform, "Reading the operator", Toolchain, Code style, Comments, and Code quality lines; Engineering Standards condensed around a Principles index (section-aware merge; home-only sections untouched). |
template/CLAUDE.md | mandatory | Claude Code Session Rules gains one line: settings changes go in the home's `.claude/`, never the user-level `~/.claude/settings.json`. |
template/SOUL.md | optional | new Writing Style bullets, the "Recommend once, then build" Core Truth, and two Boundaries; an operator's edited copy is diffed first. |
template/IDENTITY.md | optional | Core Role widened, Operational Pattern seeded, and one Safety & Privacy line (never print a secret into chat); offered as a diff because the operator owns the section. |
template/rules/typescript.md | optional | rewritten (types, narrowing, calls and runtime, house idioms); an operator's edited copy is diffed first. |
template/rules/swift.md | optional | new Types section; an operator's edited copy is diffed first. |
manual | optional | Xcode pack homes only: `.claude/rules/xcode.md` gains one line under "One build driver at a time" ("Leave the headless service itself running; stop it only when the operator says they are opening Xcode."). Add it by hand; homes without the pack skip this. |
manual | none | `/simple-simplify` no longer exists; use `engineer` (or ask to "simplify this"). |
v0.4.112026-09-23
Changed
- **`pr-adversarial` is now `adversarial-review`, and it reviews any of the operator's own
- **Init defaults to Opus at high effort.** The model question recommends Opus over Fable,
- The Claude status line shows the effort level, dimmed, beside the model name. It shows
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | replace the renamed skill grant in `permissions.allow`: remove `Skill(agent-kevin:pr-adversarial)`, add `Skill(agent-kevin:adversarial-review)`. |
template/AGENTS.md | mandatory | the reporting-skills row, the `reports/reviews/` tree comment, and the "Where Your Code Lives" sentence now name `adversarial-review`. |
settings | optional | set `"model": "opus"` and `"effortLevel": "high"` in `.claude/settings.json`. Ask with the current values shown next to the new ones. A yes sets both, even over an existing project value, because the operator is choosing on this run. Skip if the operator prefers Fable or their global default. |
manual | none | `/pr-adversarial` no longer exists; use `/agent-kevin:adversarial-review`. Existing `adversarial-*` dossiers keep working, and the `skill:` field in their frontmatter is historical. |
v0.4.102026-09-23
Added
- **`self-review` prunes first.** Before proposing anything new it runs a deletion pass
- **`graduated:` markers.** A theme carrying one drops out of the compiled Learnings; a
- `sync` nudges `self-review` 30 days after the previous run, even without new feedback.
Changed
- **Codex homes mirror pack MCP servers from `.mcp.json`.** `codex_setup` now owns a
- `TASKS.md`'s Stale section is an id index per project (id and last-update date, oldest first)
- `knowledge-compile`'s Open Questions carry only stale, contradiction and missing items; a
- `release` documents that a pushed tag never moves.
Fixed
- `memory_prune` rewrites an archived `[[memory/<date>]]` link whose daily file is gone to
- A broken `.mcp.json` or settings file names itself in the Codex generator's parse error.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | Operational Rules and most of Session Rules removed (they repeated SOUL, Memory Routing and Workflow), "Ship > Start" moves into Workflow, the Architecture references list is retired, and Platform gains "a command the sandbox blocks is the operator's to run". |
v0.4.92026-09-18
Added
- **Xcode pack.** An integration pack, not a skill pack: it makes Apple's toolchain reachable
- `templates/repo/AGENTS-apple-app.md` and `AGENTS-apple-package.md`: fill-in agent manuals for
Changed
- **`pr-review`, `pr-walkthrough`, and `pr-adversarial` fire on how the operator asks**
- **Paste blocks read like the operator wrote them.** The `pr-review` replies report is flat:
- **Diagrams in a report are Mermaid, never ASCII.** Report files are read in Obsidian and on
- `templates/rules/swift.md` gains Concurrency (no `@unchecked Sendable` to silence a
- Init seeds `.claude/rules/` by name (`typescript`, `swift`) rather than by glob, so the
- `CONTRIBUTING.md`'s new-skill frontmatter template no longer ships
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add to `permissions.allow`: `Skill(agent-kevin:pr-review)`, `Skill(agent-kevin:pr-walkthrough)`, `Skill(agent-kevin:pr-adversarial)` (the three are model-invocable now; without the grants each auto-fire raises a confirm prompt). |
template/rules/swift.md | optional | five new sections (Concurrency, Testing, Time is an input, Toolchain, Further reading) replace the old References block; an operator's edited copy is diffed first. |
manual | optional | the Xcode pack is opt-in and macOS-only: on a Mac with Xcode 27 or later, run `/agent-kevin:configure-skills` β Xcode. That walk seeds `.claude/rules/xcode.md` and `xcode-project.md` and prints the two operator steps (sandbox exclusion, sudo enablement); upgrade never copies those rules. Every other home has nothing to do. |
v0.4.82026-09-17
Added
- **`pr-adversarial`: a cross-model review loop on one dossier.** For the operator's own work
Changed
- `pr-review` carries an `adversarial-*` dossier as prior context the way it already carries a
- The dashboard cheatsheet, the GitHub pack walk, the `report_write` tool description, the
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | three lines name `pr-adversarial`: the reporting-skills row |
v0.4.72026-09-15
Added
- **Host version floors, no shims.** `mcp-server/src/hosts.ts` names the Claude Code and Codex versions
- **`bashEditDiffEnabled` in the home's settings.** Auto mode routes file edits through the Bash tool, which
- **Tools can publish MCP `_meta`.** `ToolDef.meta` is passed through `registerTool`; `compile_next`
- **The Codex user-level note recommends trusting the home.** `projects."<home>".trust_level = "trusted"`
Changed
- **Compile prompts no longer embed the manual, `USER.md`, the wiki index, or the memory index.** Every
- **The upgrade skill's gitignore step drops its `!` workaround.** The Bash tool no longer mangles a
- **The Codex SessionStart banner travels as `systemMessage` in the JSON envelope.** Codex accepts the
Removed
- **The additional-directories env setting.** 0.4.6 had `init` and upgrade write
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | optional | a home that ran the 0.4.6 upgrade holds `env.CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` in `<HOME>/.claude/settings.json`; delete the key, and the `env` block if that leaves it empty. It is inert, so leaving it changes nothing. |
settings | mandatory | `bashEditDiffEnabled: true` in `<HOME>/.claude/settings.json` (an operator's existing value is kept). |
template/AGENTS.md | mandatory | Context Loading's read-on-demand list gains the code repo's `AGENTS.md` (read with the harness bridge beside it whenever a task lands in that repo; one bullet). |
template/CLAUDE.md | mandatory | Claude Code Context Loading gains the two-file repo read: `AGENTS.md` then `.claude/CLAUDE.md`, since a manual `Read` does not resolve `@-imports` (one paragraph). |
v0.4.62026-09-15
Added
- **Swift review addendum for `pr-review`.** `references/langs/swift.md` extends the
Changed
- **`pr-review` tracks coverage, anchors by code, and protects the subjects that must not
- **`github_pr_comments` returns each inline comment's `diffHunk`**, so the reply mode
Fixed
- **Additional directories load their instruction files.** Claude Code discovers skills from
β¬ Upgrade
- Withdrawn: the settings action that added `env.CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` was removed after the key proved inert (see 0.4.7). Nothing to apply for this version.
v0.4.52026-09-13
Added
- **`pr-walkthrough`: understand, present, and record your own PR.** Author-side only, the
- **The Claude Code status line, rendered by the plugin.** `kevin statusline` draws the footer
- **Codex footer and skills budget.** `codex_setup` writes a `[tui]` status line (model with
Changed
- The user-level Codex note now recommends the model context window, read from Codex's model
- The operating manual template documents the `reports/` tree: a Memory Routing row for the
- The dashboard cheatsheet gets a "Presenting or recording your own PR" row, `report_write`
- The README's skill count reads 40.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | Memory Routing gains the reporting-skills row and Knowledge Structure gains the `reports/` tree; "Where Your Code Lives" names `pr-walkthrough`. |
template/USER.md | optional | the `GitHub login:` line names both PR skills (one clause). |
manual | optional | the status line: upgrade writes `statusLine` into `<HOME>/.claude/settings.json` when absent and re-points it when it names a stale plugin path (an operator's own line is kept); nothing to do unless the report shows a permission-error fallback, then paste the printed entry. Shows on relaunch. |
manual | optional | Codex homes: upgrade regenerates `.codex/config.toml` with the `[tui]` status line and `[skills]` budget (trust the hooks again via `/hooks`); the larger model context window is a user-level, machine-wide cost choice, so paste the pair from `.kevin/updates/codex-user-config.md` only if you want it. |
v0.4.42026-09-12
Added
- **`pr-review`: adversarial pull-request review with no GitHub write access.** Two modes,
- **`reviews` report category.** `report_write` accepts it, the dashboard orders and colors
Changed
- The dashboard cheatsheet gets a "Reviewing a PR" row, the GitHub pack walk in
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/AGENTS.md | mandatory | "Where Your Code Lives" names the `pr-review` skill among the tasks that target the code path (one clause). |
template/USER.md | optional | a `GitHub login:` line under "Where Things Live". The skill reads it to tell your PRs from teammates' and offers to fill it in on first use, so skipping this only means one extra question later. |
v0.4.32026-09-10
Changed
- **The README is a landing page; the manual lives at [dev.agentlayer.one/docs](agentlayer.one/docs).** Pitch, the loop, a quick start for both hosts, a section map into the docs site, and highlights, with the stale tool and skill counts corrected (56 tools, 38 skills). The docs site is host-neutral, serves `llms.txt` / `llms-full.txt`, and renders this changelog.
Fixed
- **Seed import refreshes the Codex rules.** The Codex rules file is generated from the `permissions.ask` entries a seed import merges into, so the seed-import skill now calls `codex_setup` when a bundle added ask entries to a Codex-wired home (`.codex/hooks.json` present); before, those commands ran unprompted under Codex until the next upgrade. `codex_setup` is also classified as a core grant by `seed_scan`, so the export interview no longer offers it as a custom entry.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.4.22026-09-09
Added
- **The Codex wiring carries the home's posture, read from its Claude settings.** The generator
- **`codex_setup` MCP tool.** Init and upgrade generate the wiring through it, since a Codex
- **A paste-ready note for the user level** (`skills/init/scripts/codex-user-config.ts`), the
- **The home's profile fills whatever the user level does not.** Claude's user-level `Read(β¦)`
- The generator is agent-neutral: names, the env prefix, and the rules file come from the plugin
Changed
- Init asks under Claude Code, every time, whether the home also runs Codex, instead of skipping
- The generator refuses a `.codex/config.toml` that still carries the legacy `sandbox_mode` or
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add to `permissions.allow`: `mcp__plugin_agent-kevin_kevin__codex_setup` (the new always-on core tool init and upgrade call to write a home's Codex wiring from outside the shell sandbox). |
manual | optional | Codex homes: run `$upgrade` (or `/agent-kevin:upgrade`) once; the wiring gains the permission profile, the rules file, and the shell env. The hook commands are unchanged, so no re-trust unless the report says `hooks.changed: true`. If the generator refuses because of legacy `sandbox_mode` keys, delete them from the home's `.codex/config.toml` and rerun. The profile replaces the sandbox the home ran under and an escalation prompt no longer lifts it: a directory the agent writes that is neither the home nor the code path goes into the Claude settings' `permissions.additionalDirectories`, then rerun. Then paste the user-level block the report points at (`.kevin/updates/codex-user-config.md`) into `~/.codex/config.toml`; every line in it is optional. Claude Code-only homes have nothing to do. |
v0.4.12026-09-07
Added
- **Codex CLI is a second host.** A checkout installs as a Codex plugin
- `bin/kevin β¦ --home=PATH` pins the agent home from the command line, setting both
- `session-start --hook-protocol=codex` prints the static stack (identity files, indexes,
- `session-capture --hook-protocol=codex` (`--format=codex`) reads Codex's rollout JSONL:
- **`upgrade` starts with a registration preflight** (`skills/upgrade/scripts/registration-check.ts`):
- **A `PreToolUse` guard on shell commands** (`bin/kevin guard`, wired in `hooks/claude.json` for
- Session block headers record the harness and model that produced the block
Changed
- Session block headers and `raw/sessions/index.json` are keyed by the **full session
- The Claude manifest declares its hooks (`hooks/claude.json`, was `hooks/hooks.json`)
- The MCP server hydrates the home's `.claude/settings*.json` env on first import
- `release` bumps both manifests; `manifests.test.ts` fails when they drift.
- The Claude developer catalog (`.claude-plugin/marketplace.json`, `agentdev-kevin`) is
- **The public marketplace is `AgentLayer1/agentlayer-agent-marketplace`**, serving Claude Code
- Every `disable-model-invocation` skill opens with a one-line operator-only guard: Codex
- The sync's brain commit sweeps `.codex/` with the rest of the home's state, so the
- README, `templates/AGENTS.md`, and the init skill name the plugin manifest as where the
Fixed
- A turn truncated (or pasted) inside a three-backtick code fence left the fence open in the
- A capture that cannot take the capture lock in time no longer proceeds unlocked or dies to
- The Codex session start delivers the identity files even when the dynamic lane fails
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | optional | the marketplace moved to `AgentLayer1/agentlayer-agent-marketplace` (Claude Code and Codex from one repo). Registered from the old `agentlayer-claude-marketplace`? Run `/plugin marketplace add AgentLayer1/agentlayer-agent-marketplace` then `/plugin install agent-kevin@agentlayer` once: both repos carry the name `agentlayer`, so the new one replaces the old, the plugin id is unchanged, and nothing in your home changes. |
manual | mandatory | a local clone registered under any name other than `agentdev-kevin` (a pre-0.4.1 directory install was registered as `agentlayer`) loads no plugin next session, because the clone's catalog is now named `agentdev-kevin`. Re-register it: `/plugin marketplace remove <old name>` (this uninstalls the plugin it brought), `/plugin marketplace add <clone path>`, `/plugin install agent-kevin@agentdev-kevin`. The upgrade's preflight prints these three lines with your paths and renames the home's `enabledPlugins` and `extraKnownMarketplaces` keys itself. Clones already registered as `agentdev-kevin` have nothing to do. Under Codex the plugin is a cache copy either way: `codex plugin marketplace upgrade agentlayer` then `codex plugin add agent-kevin@agentlayer` for the marketplace, or `codex plugin remove` and `add` of `agent-kevin@agentdev-kevin` for a clone. |
template/AGENTS.md | optional | the tree-diagram comment on `.mcp.json` now says the bundled `kevin` server is registered in the plugin manifest (one comment line; declining loses nothing). |
manual | optional | Codex: this upgrade asks once whether the home also runs Codex and, on yes, writes `.codex/hooks.json` and the `[mcp_servers.kevin]` table in `.codex/config.toml`. Then install the plugin in Codex if you have not (`codex plugin marketplace add <checkout or marketplace>`, `codex plugin add agent-kevin@<marketplace>`), launch `codex` from the home, trust the folder when asked, and trust the four Kevin entries via `/hooks`. A Codex-only home gets the same wiring from `$upgrade` run inside Codex. Claude Code-only homes answer no and have nothing to do. |
v0.4.02026-09-06
Added
- **`AGENTS.md` is the operating manual.** The agent home's manual is now a
- **`0.4.0` migration** (`skills/upgrade/scripts/0.4.0.ts`): builds `AGENTS.md` from
- `ping` reports the plugin `version` the server process loaded, so
- **The recommended auto-mode block is generated, not transcribed.**
- **Session start flags a broken manual layout.** When `AGENTS.md` exists but the
Changed
- `init` writes `AGENTS.md` and the `.claude/CLAUDE.md` bridge. A project's own
- `upgrade` maps both templates to their new homes (`AGENTS.md`, `.claude/CLAUDE.md`),
- The server resolves the manual wherever a home currently keeps it (`AGENTS.md`, the
- **Seed format: the operating-manual overlay travels as `AGENTS.md` only.** Bundles
- The status collector reads the `@-import` chain from the bridge and labels imports
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | none | **restart Claude Code after `/plugin update`, before running this |
script | required | run `skills/upgrade/scripts/0.4.0.ts` via `run_upgrade`. Moves |
template/AGENTS.md | mandatory | the operating manual. Claude Code-only mechanics |
template/CLAUDE.md | mandatory | new file at `.claude/CLAUDE.md` (the Claude Code |
template/knowledge/concepts/self-evolution-loop.md | optional | two `CLAUDE.md` β |
manual | optional | if you pasted the printed auto-mode block into |
manual | none | the migration retargets markdown links to the moved file and the one |
v0.3.332026-09-05
Fixed
- **Session radar now works on Windows.** The default scope for `where-am-i`,
Changed
- The three skills that call the radar (`where-am-i`, `find-session`, `standup`) drop
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.322026-09-01
Changed
- **Seed manual overlay now targets `CLAUDE.md`, append-only and idempotent.**
- `/agent-kevin:seed-import` now offers to render a seeded roadmap draft
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.312026-08-31
Added
- **Seed bundles: hand your agent to a teammate.** A one-shot export/import so an
- **The bundle format (formatVersion 1)** is a plain zip: `manifest.json` + payload
Changed
- **`/agent-kevin:init` can start from a seed.** New Step 1c asks whether a seed bundle
- README: new "Seed a teammate's agent from yours" use case, skills-table and CLI-table
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add to `permissions.allow`: |
v0.3.302026-08-25
Fixed
- **A planted data dir can no longer claim a directory as the agent home.** Before
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.292026-08-20
Added
- **Outbound checkpoint that survives auto mode.** Init now writes a baseline
- **Printed auto-mode guidance for the operator's user settings.** Kevin's memory
- **Three classifier soft-denies ship in the same block**, because excluding
Changed
- **Upgrade gains two every-run invariants** (not gated on this entry, so homes that
- Init documents that `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` (Kevin's own
- **The upgrade skill is model-invocable.** A plain "upgrade kevin" or "apply the
Fixed
- **Stray `curl_run` allow grants are retired.** `curl_run` is the one sanctioned
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | union the baseline `permissions.ask` list into project |
settings | optional | remove `mcp__plugin_agent-kevin_kevin__curl_run` from |
manual | optional | paste the printed auto-mode block (`permissions.defaultMode`, |
v0.3.282026-08-20
Added
- `standup` skill β your update in the three parts a standup actually has: what you
- `find-session` skill β locate a past session by *what it worked on* (a branch, a PR
- README: **Running homes on different Claude accounts** β `CLAUDE_CODE_OAUTH_TOKEN`
Changed
- **Sync's briefing auto-select is catch-up-aware.** It used to read the clock alone,
- `where-am-i`'s description now points at `find-session` for content-shaped asks, so
Fixed
- **The session radar no longer trusts file mtimes for recency.** Claude Code touches
Removed
- `permission-check` skill, and the `permissions` report category it was the only
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add to `permissions.allow`: `Skill(agent-kevin:find-session)`, |
settings | optional | `Skill(agent-kevin:permission-check)` is now a dead grant and |
v0.3.272026-08-17
Added
- **A roadmap is a convention now, not config.** `roadmap.html` lives at the root of
- `create-project` points new projects at the convention (and says not to scaffold an
Changed
- **Flywheel is framed by the roadmap.** It reads the north star's `ROADMAP` object
Fixed
- README's MCP tool count was stale in two places (47 in the tool table, 48 in the
- The sidebar's health and upgrade badges ran past the edge of the fixed-width
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | optional | only if you keep a project roadmap at the old nested path |
v0.3.262026-08-13
Added
- **Name your agent something other than Kevin.** The display name and the plugin
- **`rename-agent` β rename an existing home.** Rewrites the persona fields, swaps the
- **Unresolved scaffold placeholders are surfaced every session.** `init` and `upgrade`
Changed
- **A home is identified by its data dir, never by `SOUL.md`.** Every agent's home has a
- **User-level session hooks are no longer supported.** Capture ships only with the
- **The CLI and the MCP tools refuse to run outside this agent's home.** Both name the
- **README rewritten around the launch-from-home convention**, replacing the
Fixed
- **The logger forged the marker that identifies a home.** It created the data dir on
- **Field readers walked past an empty value into the next line.** `\s` matches
- **Guards no longer recommend a destructive repair.** SessionStart told a home with a
- **A blocked task can be cancelled without a detour through `active`**, which had been
- **`browser_flows` drives chromium over CDP on native Windows** (#17).
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | required | **Delete the `session-capture` hooks and any `KEVIN_HOME` from |
manual | none | **restart Claude Code after `/plugin update`, before anything else.** |
template/CLAUDE.md | mandatory | placeholder-only change. Upgrade resolves |
template/SOUL.md | optional | same placeholder-only change, and it's confined to the |
v0.3.252026-08-10
Added
- **`list_worktrees` β read-only worktree triage.** The audit sibling of
- **`github_pr_comments` β the GitHub pack can finally read a review.** `gh pr view`'s
Fixed
- **Hooks silently degraded when a session roamed out of the HOME tree.** The home
- **`github_pr_view` no longer 403s on repos where CI reports as check runs.** It
- **GitHub-pack docs matched back to reality.** The README tool table had drifted
Changed
- Sync's fast-forward docs teach the shared `AGENT_*` env spellings, with the
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | additive | if you use the GitHub pack, add |
manual | none | if your fine-grained PAT was minted from the old walk, check it |
v0.3.242026-08-07
Added
- `configure-skills` Section B β a guided walk for registering **external remote MCP
Fixed
- **Browser OAuth tab storm from hand-rolled remote-MCP wrappers.** `mcp-remote`
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | required | if your `<HOME>/.mcp.json` registers any `mcp-remote` server |
v0.3.232026-08-06
Added
- **Sync commits the brain.** A new step 11 runs `skills/sync/scripts/commit-brain.ts` after the dashboard render, so each run's own outputs land in history instead of waiting for someone to remember. The script is the guard, not the model: it acts only when the HOME repo is on `main`/`master` with **no remote configured**, and it never pushes and never amends. Changes are grouped into ordered commits (`Sync: update knowledge`, `Sync: update projects`, `Sync: save reports`, `Sync: update state`) so the log stays readable. Untracked files outside those roots are reported back as `leftUncommitted` rather than swept in, and `.gitignore` still fences secrets. Covered by a 10-case guard matrix including the split-git-dir topology.
Changed
- Sync's output block gains a `πΎ Brain` line, and the closing interview moves to step 12.
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | optional | no action for a normal HOME whose `.git` lives inside the home directory; sync will just start committing. If your HOME uses a **split git dir** (the git directory outside the home tree), grant that path in `.claude/settings.local.json` under `permissions.additionalDirectories` and the sandbox's `filesystem.allowWrite`, or step 11 will report `COMMIT_BLOCKED` and change nothing. A HOME repo with a remote configured is skipped by design, since pushing stays your workflow. |
v0.3.222026-08-06
Added
- **Agent-neutral env naming.** Every config knob now has a shared, agent-neutral `AGENT_*` name alongside this agent's own spelling (`KEVIN_*`), which is derived from the plugin manifest name and always wins. The fork seam collapses to `plugin.json` plus one test assertion. New side-effect-free `shared/naming.ts` owns the prefix, the shared/override resolution rule, and the runtime data-dir name (`AGENT_RUNTIME_DIR` override, validated as a bare folder name). Existing `KEVIN_*` configs work unchanged β no migration.
- **Init asks which model Kevin runs on** (Fable default vs Opus) and writes the literal value to settings.
- **Relocatable reports root.** Init's custom-paths step now covers `reports/` alongside `knowledge/` and `projects/` (`AGENT_REPORTS`), grants the outside-home permissions, and derives `plansDirectory` from the resolved path.
- Onboarding plants HOME-scoped env keys under the shared `AGENT_*` spellings; the README documents the two-spelling rule.
Fixed
- Prefix derivation fails loud on a missing or malformed plugin manifest instead of silently disabling every per-agent override.
- The home walk-up and the flow-env secrets gate both honor the default runtime-dir name during a rename migration window, so the secrets store can't be resolved under (or read from) the wrong root.
- The logger no longer scaffolds a runtime dir in a foreign cwd β a plugin hook firing in someone else's checkout logs to stderr only. Log level/file gain the per-agent override spellings.
- Bash-driven skills (where-am-i, setup-worktree, init snippets) resolve env vars with the chained two-spelling form instead of reading one spelling literally.
- The browser-flows harness reads the canonical `AGENT_HOME` instead of throwing on a missing per-agent variable.
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | none | everything is backward-compatible; existing `KEVIN_*` settings keep working. Optionally rename HOME-scoped keys (`.claude/settings.local.json` env, `.kevin/secrets/.env` `KEVIN_DB_*`) to the shared `AGENT_*` spellings for portability β keep `KEVIN_HOME` prefixed in machine-wide `~/.claude/settings.json` on multi-agent machines. |
v0.3.212026-08-05
Fixed
- **`init`'s prerequisite gate could pass on a Mac with no developer tools installed.** The checks used `command -v`, but on macOS `/usr/bin/git` and `/usr/bin/python3` are xcode-select shims β one shared ~118KB binary hard-linked under roughly 78 tool names β that sit on PATH whether or not the Command Line Tools exist. So `command -v git` succeeded on a machine with no git, init declared prerequisites met, and the failure only surfaced later when something tried to use it. Exactly the fresh-Mac case a non-technical operator arrives with. Verified 2026-08-05: with the developer directory unresolvable, `command -v git` passes while `git --version` exits 1. Hard requirements are now **functional probes** (`bun --version`, `git --version`, `python3 --version`), which also catch a broken install generally.
- **A failing `git` on macOS now names the right remedy.** `xcode-select -p` is checked, and when the tools are absent init prints `xcode-select --install` and stops β rather than pointing at a git-scm.com download, which doesn't address the actual cause.
Added
- **Homebrew is surfaced conditionally, not required.** Nothing in either plugin calls `brew`; it's only the install path for `gh`/`poppler` on macOS. So it's mentioned only when one of those is missing and the operator would otherwise hit a second wall mid-fix.
- **`init` probes for `gh`.** The prereq gate checked `bun`, `git`, `python3` and `pdftoppm` but not `gh` β so a missing GitHub CLI passed cleanly and then threw `gh CLI not found on PATH` mid-session from the first GitHub-pack call, including sync's code refresh. Now surfaced as a conditional NOTE ("needed only if you activate the GitHub pack"), since nothing outside that pack uses it. The prose also records where the macOS toolchain actually comes from: `git` and `python3` ship with the Xcode Command Line Tools and need no Homebrew, whereas `gh` is bundled with neither Claude Code nor this plugin and therefore does.
- **The GitHub pack walk checks `gh` before granting.** `configure-skills` stated the requirement in prose but never verified it, so the pack could activate cleanly and fail on first use. It now probes and offers a choice β continue and install after, or stop and come back β rather than hard-stopping, because the PAT-minting steps are still worth doing in the same sitting.
Changed
- **The GitHub pack is default-ticked when a code path was given at Step 4b.** `github_fast_forward` needs `GITHUB_TOKEN`; without the pack it returns `NOT_CONFIGURED` and the operator's checkouts silently never refresh. That's the one failure mode that degrades *answers* rather than raising an error β Kevin keeps grounding confidently against a frozen checkout β and an operator who just told init where their code lives has effectively asked for the opposite. Still unticked when Step 4b returned `skip`, which stays the common case for a Kevin home.
β¬ Upgrade
| change | level | detail |
|---|---|---|
manual | none | if you activated the GitHub pack before this release, confirm `gh` is on your PATH (`command -v gh`; macOS `brew install gh`). Nothing else to reconcile. |
v0.3.202026-08-05
Added
- **`github_fast_forward` β sync step 0 moves into the GitHub tool family.** Fast-forwards the default branches of the configured checkouts by **slot** (first local match of `main`/`master`, and of `develop`/`dev`), so a vestigial `master` beside a live `main` is never touched. Authenticates with the existing fine-grained read-only PAT over HTTPS: one `fetch --prune` per repo, then every ref update is local and needs no credential. The checkout's own remote is neither used for transport nor rewritten, so an SSH remote keeps working for the operator's own pushes. Guard matrix pinned by tests in `mcp-server/src/tools/github.test.ts`.
Fixed
- **Sync step 0 was a guaranteed no-op in any sandboxed session.** It ran `git fetch` through the Bash tool, and the Claude Code seatbelt gives non-proxied clients no DNS at all β so every repo with a `git@github.com:` remote failed at hostname resolution. It also reported that as `FETCH_FAILED`, conflating "no egress from this process" with "this repo is broken." Moving the work into the MCP server (which runs outside the sandbox, the same reason the rest of `github_*` lives there) fixes it, and `FETCH_FAILED` now carries a `reason` of `NO_ACCESS` / `AUTH` / `NETWORK` so the report says which.
- **A PAT the org hasn't approved is no longer misreported as a bad credential.** Verified against a live org: GitHub answers `403` on the git endpoint in that case, which the classifier scored as `AUTH` β telling the operator to re-mint a token that was perfectly valid. `AUTH` is now only for a credential GitHub rejects outright; `403`, `404 Repository not found`, and `permission denied` all read as `NO_ACCESS`, whose fix is the Contents grant plus org approval.
- **The GitHub PAT scope list was missing `Contents: Read`** and actively told operators they didn't need it. `git fetch` authenticates against `Contents`, so a token minted from the old instructions fails the fast-forward as `NO_ACCESS` while the PR and issue tools work fine. `Contents: Read` confers no push ability; writing needs `Contents: Write`, which is never requested.
- **`config` froze every filesystem path at import time, so whichever module imported it first decided where the whole process wrote.** Anything that set `KEVIN_HOME` afterwards β a hook, the CLI, a test fixture β was silently ignored. `FOLDERS` and `FILES` are now getters that resolve live per access, so the existing call sites are unchanged and import order no longer decides anything.
- **Secret loading had the same import-time freeze.** `loadSecretsEnv()` latched on a boolean and ran eagerly at import, so the first module to pull `shared/env` decided which home's `.kevin/secrets/.env` the process used forever β the per-read calls could never correct it, making the module's own "no import-order discipline to forget" promise untrue. It's now keyed on the resolved secrets file, so a changed `KEVIN_HOME` re-reads (and drops the previous store's keys so they can't leak across homes).
- **Six modules still froze a home-relative path at import, re-introducing the import-order hazard the getters removed.** `session-capture`'s lock dir, `status/collect`'s TASKS.md path, `browser-flows`' HOME flows dir, `google-auth`'s secrets subpaths, and the captures dir in `tools/browser` + `media/frames` were all module-scope `const`s built from `FOLDERS` getters β frozen to whatever home was current at first import. Each now resolves at call time (the two captures dirs reuse config's existing `BROWSER.CAPTURES_DIR` getter instead of re-deriving the path); `google-auth`'s unconsumed `CLIENT_FILE` export dropped along the way.
Changed
- **`init` no longer grants the fast-forward git verbs** (`git fetch`, `git merge --ff-only`, `git rev-parse`, `git show-ref`). They existed only for the Bash version of step 0; the MCP tool needs none of them, so the baseline goes back to being tighter.
- **Step 0 is now GitHub-pack-gated, and never fails the chain.** A home without `GITHUB_TOKEN` gets a `NOT_CONFIGURED` report rather than a tool error, and a home with no codebase at all β common for Kevin β reports an empty list instead of erroring, so the rest of the sync chain runs untouched either way.
- **`config` owns the configured-checkout list.** `configuredRepoPaths()` (`KEVIN_CODE_PATH` plus `KEVIN_GIT_REPOS`, deduped after tilde expansion) and `extraGitRepos()` both live there and resolve live, replacing a frozen `EXTRA_GIT_REPOS` const and a duplicate parse inside the GitHub tool. Tilde expansion now happens once, at the input boundary.
- **`expandTilde` has one owner.** Three copies had accumulated in `config.ts`, `shared/env.ts`, and `shared/utils.ts` β every shared home for it blocked by an import cycle β and they had already drifted, with two handling `~/foo` but not a bare `~`. It now lives in `shared/paths.ts`, a stdlib-only leaf every layer can import. A follow-up sweep found two more private variants (`tools/github.ts`, plus an inline one in `media/frames.ts` that mangled a bare `~`); both now import the shared helper, and the `bunfig.toml` comment now says "agent home" rather than a specific env var, so the file stays fork-agnostic.
- **Five workaround rationales corrected, one simplification taken.** `curl.ts` no longer imports `@/config` lazily inside its handler to dodge the freeze; `status/html.ts`, `status/html.test.ts`, `tasks/prefix.test.ts`, `tools/upgrade.test.ts`, and `shared/env.ts`'s header all described a constraint that no longer exists. `bin/kevin` keeps its dynamic imports β the specifiers are computed from the plugin root, so they cannot be static, and they load one subsystem per invocation instead of all of them β but its comment now names those reasons instead of the env-ordering one.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | additive | add `mcp__plugin_agent-kevin_kevin__github_fast_forward` to `permissions.allow` if you use the GitHub pack, so `/agent-kevin:sync` step 0 doesn't confirm per run. |
template/CLAUDE.md | mandatory | new "Scratch files get a `mktemp` name" rule under Platform ($TMPDIR is per-user, concurrent sessions clobber fixed names). |
manual | none | if you minted your PAT before this release, add **Contents: Read** to it (Repository permissions, read-only). Without it step 0 reports `NO_ACCESS`. Everything else in the GitHub pack keeps working either way. |
v0.3.192026-08-03
Added
- **`sync` step 0 β fast-forward the code checkouts.** Before the knowledge chain runs, sync fetches every repo in `KEVIN_CODE_PATH` + `KEVIN_GIT_REPOS` and fast-forwards whichever of `main` / `master` / `develop` / `dev` already exist locally. Makes `/agent-kevin:sync` the single command a non-technical operator ever has to run β code freshness rides along instead of being a git chore they'd have to remember. Engineers benefit too: default branches in reference checkouts stop drifting weeks behind. Both env vars are optional, so a Kevin with no codebase configured skips the step silently. Strictly forward-only and heavily guarded β only branches that already exist locally are touched (never conjures a `develop`), non-fast-forward updates are refused rather than forced, a dirty checked-out branch is reported as `SKIPPED_DIRTY` and left alone, main checkouts only (a worktree's `.git` is a file), and a failed fetch degrades to a report line instead of failing the sync. Outcomes surface in a new `π₯ Code` block.
Changed
- **`init` grants the fast-forward git verbs** (`git fetch`, `git merge --ff-only`, `git rev-parse`, `git show-ref`) in the baseline `permissions.allow`, so sync's step 0 doesn't prompt mid-run. Nothing destructive is added β force/reset/rebase stay denied.
Fixed
- **`upgrade` no longer reconciles a home against a stale template set when the loaded plugin is a version-pinned cache dir.** The version still comes from `CLAUDE_PLUGIN_ROOT` (never `installed_plugins.json`, whose record lags a directory-type marketplace), but when that root is a `plugins/cache/<mkt>/<plugin>/<version>` copy, the skill now reads the marketplace source's `plugin.json` and reports `available=`. A newer source version stops the run with the `/plugin marketplace update` β `/plugin update` β restart path, because the CHANGELOG bundled beside a pinned copy cannot describe migrations released after it. Advisory and best-effort: any lookup miss leaves `available` empty and changes nothing.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | additive | add `Bash(git fetch *)`, `Bash(git merge --ff-only *)`, `Bash(git rev-parse *)`, `Bash(git show-ref *)` to `permissions.allow` so `/agent-kevin:sync` can refresh your checkouts without a prompt per repo. Union merge, nothing removed. |
v0.3.182026-08-03
Added
- `where-am-i` checkpoint mode (`/agent-kevin:where-am-i checkpoint`): writes a short pickup note for the *current* session as a chat reply, so the SessionEnd capture files it into knowledge. Incremental by construction, no cursor or state file.
- Dashboard **Surfaces** group in the sidebar, discovered from disk on every render: a HOME-root `roadmap.html` leads, then every `projects/<slug>/dashboard.html`, alphabetically. Zero config, no registry.
- Malformed-task health signal: task files whose frontmatter won't parse are collected and surfaced as a warning callout in `TASKS.md` plus a fifth blocking dashboard signal, instead of silently vanishing from every scan.
- `init` recommends the split layout (`~/Documents/Agents/<AgentName>` for the home, repos in a separate code tree), refuses to scaffold into a code repo without confirmation, and flags iCloud Documents sync.
Changed
- Agent home resolution goes through a shared `.kevin`-marker walk-up (`agentHomePath()` / `isAgentHome()`): `KEVIN_HOME` wins, else walk up from cwd anchoring on this agent's data dir, else cwd (pre-init only). A session launched inside a code repo can no longer anchor `.kevin/` state, captures, or logs to that repo.
- Mutating skills (`upgrade`, `sync`, `configure-skills`, the goals watermarks, cadence) fail loud with `NOT_AN_AGENT_HOME` rather than writing into whatever tree the session ran in. The goals skills' inline watermark one-liners collapse into a shared `watermark.ts`.
- `init` writes `permissions.additionalDirectories` and `sandbox.filesystem.allowWrite` for the **code root** whenever `KEVIN_CODE_PATH` resolves outside the home, and derives `KEVIN_GIT_REPOS` from the main-checkout repos beside it (`.git` directories only, so sibling worktrees don't flood the list).
- `where-am-i` takes comma-separated scope roots (cwd + home + code root) so the radar sees home and code-repo sessions across separate trees; `setup-worktree` guidance points at the code root.
- `api-collections` Bruno adapter notes the Bruno v4 deltas (`setEnvVar` now persists β secrets rule); `roadmap` render check notes the entry-animation blank-section pitfall.
Fixed
- Session radar prefers an operator's `/rename` custom title over the first-prompt auto-title (matching Claude Code's own `customTitle || aiTitle` precedence), so restored sessions stop being named after the "catch up and continue" instruction.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/CLAUDE.md | mandatory | Knowledge Structure and Git Worktrees sections describe the split layout (`~/Documents/Agents/<AgentName>` home, repos in a separate code tree). |
settings | optional | when your code tree lives outside the home, add `permissions.additionalDirectories: ["<CODE_ROOT>"]` and `sandbox.filesystem.allowWrite: ["<CODE_ROOT>"]` (code root, not a single repo, so sibling worktrees and a separated agent git dir stay writable). Skip for nested homes or homes with no code path. |
manual | none | **restart Claude Code after `/plugin update`, before syncing.** This release changes MCP-server code (home resolution, dashboard, task scan); the running server holds the old code until Claude Code reloads, so a sync before the restart runs against a stale server. |
manual | none | optionally widen `KEVIN_GIT_REPOS` in `.claude/settings.local.json` to the repos beside `KEVIN_CODE_PATH` (comma-separated) for a fuller SessionStart git-activity block. |
v0.3.172026-07-30
Added
- `roadmap` skill: wizard-built strategic roadmap surfaces β interviews for the frame (shape, horizons, lanes, accent scheme), harvests milestones from the task board / READMEs / git history, renders a self-contained dark/light HTML page from the house template (`references/template.html` + `DESIGN.md`). Model-invocable; fires on "roadmap", "north star", "plan-on-a-page" asks.
- Accent-scheme presets in the roadmap wizard: purple (template default), green, gold, or a typed hue via Other; `DESIGN.md` carries the token sets and per-preset dark tints.
Changed
- `init` allow list gains `Skill(agent-kevin:roadmap)` so auto-invocation never prompts.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add permission `Skill(agent-kevin:roadmap)`. |
v0.3.162026-07-24
Added
- Dashboard operator card is travel-aware: when `KEVIN_HOME_TIMEZONE` differs from the machine's live timezone, the card (sidebar + Profile header) stacks `π <home>` over `βοΈ <current>`. At home it stays a single plain timezone line, unchanged.
Changed
- `morning-briefing` and `sync` skills name the Perplexity `web_search` tool explicitly instead of built-in `WebSearch`, so the briefing's news pull uses the intended provider.
Fixed
- Dashboard operator card renders only the IANA token of the home timezone, stripping any annotation carried on the timezone field.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.152026-07-24
Added
- Travel-aware timezone: set `KEVIN_HOME_TIMEZONE` (IANA name) in `.claude/settings.local.json` `env` β `init` now writes it from Step 4. When it differs from the machine's live timezone, the SessionStart `## Today` line appends `βοΈ traveling (home: <tz>)`. Unset leaves output unchanged.
Changed
- `templates/USER.md` + `init`: the single **Timezone** identity field splits into **Home timezone** (static home base) and **Current timezone** (read from the session context's `## Today` line, follows travel).
- Morning/evening briefings compute the Hijri date in the operator's **current** timezone (the `## Today` line), falling back to the home timezone in `USER.md`.
- Dashboard operator card reads the new **Home timezone** field, with fallback to the legacy **Timezone** label.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/USER.md | optional | Timezone line splits into Home/Current timezone. |
script | required | runs `skills/upgrade/scripts/0.3.15.ts`: seeds `KEVIN_HOME_TIMEZONE` in `.claude/settings.local.json` `env` from USER.md's home timezone (no-op if already set; reports when USER.md has no valid IANA name so the operator can set it by hand). |
v0.3.142026-07-23
Added
- `where-am-i` **triage mode** (`/agent-kevin:where-am-i triage [scope]`, or when the operator asks "what should I tend to / work on next / which session needs me"): ranks the live sessions by what most needs a human (decision-pending, importance, momentum), presents the top few via an `AskUserQuestion` interview, and hands back the `claude --resume` command for the chosen one. Ephemeral β no report.
- `where-am-i` standard digest now leads with a compact index table (one row per session, state emoji first) above the buckets; skipped when there are β€2 sessions.
- `init` prerequisite check now notes `poppler` as an optional dependency β the Read tool renders PDF pages via its `pdftoppm` binary (`brew install poppler` / `poppler-utils`).
Changed
- `init` engineering defaults: when a built-in tool reports a missing dependency, relay its install hint and stop rather than improvising a fragile fallback.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.132026-07-16
Added
- `api-collections` skill: draft API request collections the operator opens and fires from their own client. Client-agnostic core with per-client **adapters** (Bruno shipped; plain-`curl` fallback when no client is installed). The Bruno adapter warns about its silent soft-failures (malformed-YAML drop, `.env`-read-at-open, unresolved-placeholder false green) and parse-checks each file after authoring.
- `curl_run` MCP tool: run an authored request end-to-end to verify it before handing it off (the api-collections verification path).
- `browser_screenshot` and `browser_pdf` accept a CSS-injection input to tweak the page before capture (#16).
- Flow-scoped secrets (`.env`) and QA fixtures (`config.json`) for HOME browser flows.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add two allow-list entries to the HOME's `.claude/settings.json`: `mcp__plugin_agent-kevin_kevin__curl_run` (new always-on core tool) and `Skill(agent-kevin:api-collections)` (new model-invocable skill). |
v0.3.122026-07-13
Added
- `browser_flows` now discovers flow definitions from the HOME's `.claude/browser-flows/` directory, so an operator can author reusable browser flows in their own home alongside the plugin-shipped ones.
Fixed
- Robust worktree teardown on native Windows: kills processes holding the worktree, requires PowerShell 7+ (`pwsh`), and fully tears down the checkout instead of leaving a husk.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/CLAUDE.md | mandatory | new note under the Platform section: on native Windows, PowerShell 7+ (`pwsh`) is required (scripts never use the built-in 5.1 `powershell.exe`). |
v0.3.112026-07-12
Added
- `video_frames` MCP tool β extracts still frames from a local video for visual analysis, running outside the Bash sandbox so it can read videos in `~/Downloads`, `~/Desktop`, `~/Documents` (which ffmpeg-under-Bash can't). Modes: `scene` (default β one frame per visual change, ideal for screen recordings of a flow), `interval`, `count`. Requires `ffmpeg` on PATH.
- `mermaid` skill β validates and iterates on a Mermaid diagram before it ships (Tier 1 parse-check every block; Tier 2 render + visual critique for diagrams headed to a rendered surface). Runs on `/mermaid`.
- `permission-check` skill β interprets a Claude Code permission prompt from a screenshot (or text) and grades how safe it is to allow (π’/π‘/π΄), then writes a graded report so repeated decisions build a corpus for future allowlist automation.
- `permissions` report category β home for `permission-check` output; surfaces as a dashboard filter chip.
Changed
- Database tools (`database_query`, `database_schema`, `database_fork`) now accept any legal Postgres database name, not just a fixed pattern.
- README refresh.
β¬ Upgrade
| change | level | detail |
|---|---|---|
deps | required | new dep `mermaid` (~11.16.0); run `bun install` in `mcp-server`. |
settings | mandatory | add to `permissions.allow`: `mcp__plugin_agent-kevin_kevin__video_frames`, `Skill(agent-kevin:mermaid)`, `Skill(agent-kevin:permission-check)`. |
manual | none | `video_frames` needs `ffmpeg` on PATH to run (`brew install ffmpeg`); only required if you use the tool. |
v0.3.102026-07-09
Added
- `CLAUDE.md` template now carries a **truncated-read verification** rule in `## Workflow`: a partial file read is never a basis for a conclusion β when a Read returns a partial view (or you've only seen part of a query, match-set, or config), page through or grep the rest before asserting, labeling, or acting on it.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/CLAUDE.md | mandatory | add the truncated-read verification bullet to your HOME `CLAUDE.md` β `## Workflow` (right after the "Verify before claim" line). |
v0.3.92026-07-09
Added
- `CLAUDE.md` template now carries a **forward-only git** rule in `## Workflow`: fix a bad commit with a new commit on top (`git revert` or a corrective commit), never `--amend`, `rebase -i` squash/fixup, or `reset` + rebuild β even when local and unpushed.
Changed
- `sync` skill's step-11 closing interview + "Suggested next moves" now freshness-check every candidate against current ground truth (task frontmatter, live artifacts, today's deltas) before offering it, so it stops surfacing next-moves the operator already completed.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/CLAUDE.md | mandatory | add the forward-only git bullet to your HOME `CLAUDE.md` β `## Workflow`. |
v0.3.82026-07-09
Added
- `remove_worktree` MCP tool β safe git-worktree teardown that runs outside the Bash sandbox (so `git worktree remove` can write the main repo's `.git/config`). Refuses on uncommitted changes (`blocked-uncommitted`), gates committed-but-unpushed work behind an explicit `force` (`blocked-unpushed`), supports a `dryRun` pre-check, never `--force`-removes, runs the repo's `clean` script when present, and leaves the branch intact unless `deleteBranch` is set. Deliberately **not** granted in `settings.json`: it's destructive, so each call prompts for confirmation.
- `setup-worktree` skill gained a **drop/teardown flow** (dry-run pre-check β unwire the VS Code workspace β remove) and, when the GitHub pack is configured, surfaces the branch's PR state to reframe a merged-branch "unpushed" result and frame the branch-delete ask.
- Native-Windows headless-browser support: Chromium is driven over CDP with a `ws` transport, working around a Bun pipe-transport hang; ships a pinned `playwright` (`1.60.0`) with a `playwright-core` patch.
β¬ Upgrade
| change | level | detail |
|---|---|---|
deps | required | new dependency `ws`; `playwright` pinned to `1.60.0` with a `playwright-core@1.60.0` patch. Run `bun install` in `mcp-server`. |
v0.3.72026-07-06
Fixed
- Report-writing skills (`where-am-i`, `flywheel`, `morning-briefing`, `evening-briefing`, `self-review`, `weekly-goals`, `monthly-goals`, `yearly-goals`) now surface the absolute `path` returned by `report_write` instead of the relative `relPath`, so the "π Saved to β¦" line is command-clickable in any terminal (e.g. cmux) without a base directory.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.62026-07-01
Changed
- `.env` deny baseline in `/init` narrowed: the catch-all `Read(**/.env.*)` is replaced by explicit denies for the secret-bearing variants (`.env.local`, `.env.*.local`, `.env.development`, `.env.production`, `.env.staging`, `.env.test`). Template files (`.env.example`, `.env.sample`, `.env.template`) now read freely, since Claude Code evaluates deny before allow with no glob negation, so narrowing the deny is the only way to whitelist one file. The bare `.env` stays denied; secrets in `.kevin/secrets/` are unaffected.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | optional | in `.claude/settings.json` β `permissions.deny`, replace `Read(**/.env.*)` with `Read(**/.env.local)`, `Read(**/.env.*.local)`, `Read(**/.env.development)`, `Read(**/.env.production)`, `Read(**/.env.staging)`, `Read(**/.env.test)`. Purely a relaxation so `.env.example` becomes readable; skip if you prefer the broader deny. |
v0.3.52026-06-30
Added
- `sync` now closes with a next-steps interview: after the dashboard render, it turns the surfaced backlog into a single `AskUserQuestion`. Pick a concrete next move (a suggested move, a flagged overdue/stale item, a due cadence skill, or a pending upgrade), then act on it now or queue it as a task. Gated to fire only when something is actually surfaced; a clean bill still ends on the `β Sync complete` one-liner. Cadence/upgrade picks collapse to surfacing the slash command (they stay operator-gated).
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.3.42026-06-25
Added
- Read-only GitHub pack: nine MCP tools that shell out to `gh --json` β `github_pr_list` / `github_pr_view` / `github_pr_diff` / `github_pr_checks`, `github_run_list` / `github_run_view` / `github_run_log`, and `github_issue_list` / `github_issue_view`. Lets Kevin review PRs and issues, pull diffs and check status, and diagnose failing GitHub Actions runs (failed-step logs). No write subcommands β commenting, merging, and re-running workflows stay human-in-terminal by design. Runs from inside the MCP server (outside the Bash sandbox, where `gh`'s keychain TLS would otherwise fail), authenticating via a `GITHUB_TOKEN` from `.kevin/secrets/.env`. Repo defaults to `origin` of `KEVIN_CODE_PATH` / first `KEVIN_GIT_REPOS` entry; override per-call with `repo="owner/repo"`.
- GitHub is now an opt-in pack in `/init` and `configure-skills` (new A.2d walk), alongside SEO / Browser / Database.
Changed
- `self-review` and `yearly-goals` skills now persist their summaries via the `report_write` MCP tool, so each run leaves a durable report in the audit trail.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | optional | the GitHub pack is opt-in. To activate, run `/agent-kevin:configure-skills` (GitHub walk): it grants the nine `github_*` tool permissions, ensures `.kevin/secrets/.env`, and surfaces the steps to mint a fine-grained read-only PAT (`GITHUB_TOKEN`). Requires the `gh` CLI on PATH (`brew install gh`). Existing homes are unaffected until they opt in. |
v0.3.32026-06-25
Added
- Sync now surfaces cadence nudges: planning and review skills (the weekly/monthly/yearly-goals trio + self-review) that have come due are listed with the exact slash command to run, driven by a `cadence` block in each skill and a shared `skills/sync/scripts/cadence.ts`.
- Dashboard Skills tab gained auto/manual filter chips so you can split model-invocable skills from slash-only ones.
- `kevin` CLI gained a `database` command group (list/schema/query/fork) mirroring the Database MCP tools for use outside Claude Code.
Changed
- Consolidated every `process.env` read into a single config-free `shared/env.ts` module. Secret-reading tools (web-search, serpapi, open-page-rank, gsc, database, database_fork) now self-load `.kevin/secrets/.env` on first access regardless of import order, instead of relying on a sibling importing `config.ts` first. A build-time guard test fails if any module outside `shared/env.ts` reads `process.env` directly.
- self-review skill: fixed path drift, added an output watermark and a template-promotion track.
- Dashboard settings/env/secrets tables now wrap long values instead of overflowing.
Fixed
- Sandbox secrets deny never bit. v0.3.0/v0.3.1 wrote the secrets deny under `sandbox.filesystem.read.denyOnly` β the harness's internal *resolved* shape, not a real settings input key β so Claude Code silently ignored it and files nested under `.kevin/secrets/` (Google OAuth tokens, `.kevin/secrets/.env`) stayed readable by sandboxed Bash, even though `ls` of the dir was blocked. The real key is `sandbox.filesystem.denyRead`; pointing it at the directory (no glob) denies it and everything under it at the OS level, which also sidesteps the gitignore `**`-won't-descend-into-`.kevin` dot-dir trap. `/init` now scaffolds `denyRead` plus a forward-compatible `sandbox.credentials.files` entry (honored on Claude Code v2.1.187+, ignored on older).
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run `skills/upgrade/scripts/0.3.3.ts` via the `run_upgrade` MCP tool. It drops the dead `sandbox.filesystem.read.denyOnly` key, adds `sandbox.filesystem.denyRead: [".kevin/secrets"]`, and seeds `sandbox.credentials.files`. Idempotent. |
manual | none | restart/reload Claude Code after the migration so Seatbelt loads the corrected policy. Verify with `wc -c < .kevin/secrets/<a-token-file>` β it should report "Operation not permitted" (not a byte count). |
v0.3.22026-06-24
Added
- New `database_fork` MCP tool: clones a Postgres database into a private copy via `CREATE DATABASE <fork> TEMPLATE <source>` (pure SQL, no `pg_dump`/`pg_restore`, cross-platform), so risky or destructive schema work runs against a scratch copy instead of a shared/live DB. Refuses remote hosts (local only), defaults to the first connection, names the fork after the current git branch, can repoint an env file at the fork, and tears down with `drop: true`. This is what `setup-worktree` now uses to give a worktree its own database on demand.
- Dashboard now shows a presence-only secrets inventory of `.kevin/secrets/` (env key names + Google OAuth files): names and presence checks only, never values.
Changed
- Database tools renamed for consistency: `db_list` β `database_list`, `db_schema` β `database_schema`, `db_query` β `database_query`. Consumer-visible (permission grants change; see Upgrade).
- `setup-worktree` skill wires up `database_fork` to provision a worktree's database.
- README database section rewritten for the v0.3.0 secrets layout: `KEVIN_DB_*` connection strings now live in `.kevin/secrets/.env`, not `settings.local.json`.
Fixed
- Hardened the not-yet-released `0.3.0.ts` / `0.3.1.ts` secrets migrations: purge the old `settings.local.json` env block after relocation and strengthen the secrets deny path.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | only if you use the Database pack. Replace the renamed tool grants in your project `.claude/settings.json`: remove `mcp__plugin_agent-kevin_kevin__db_list`, `mcp__plugin_agent-kevin_kevin__db_query`, `mcp__plugin_agent-kevin_kevin__db_schema`; add `mcp__plugin_agent-kevin_kevin__database_list`, `mcp__plugin_agent-kevin_kevin__database_query`, `mcp__plugin_agent-kevin_kevin__database_schema`, `mcp__plugin_agent-kevin_kevin__database_fork`. |
v0.3.12026-06-24
Fixed
- Completed the secret-file deny baseline for homes upgraded via the contract. v0.3.0 broadened `/init`'s `permissions.deny` (the dotenv / cert / credential globs plus the two `curl β¦ | sh` Bash denies) and its narrow sandbox `denyOnly`, but the v0.3.0 migration wrote only the secrets-dir Read deny β so a home that ran `/upgrade` (rather than a fresh `/init`) was left with just `Read(**/.kevin/secrets/**)` and missed the rest of the hardening.
Changed
- `google-auth` tool gained a comment documenting the secrets-dir layout (parity with the worktree).
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run `skills/upgrade/scripts/0.3.1.ts` via `run_upgrade`. Tops the project `.claude/settings.json` up to the full `/init` baseline: adds the remaining Read denies (`**/.env`, `**/.env.*`, `**/secrets/**`, `**/credentials/**`, `**/*.pem`, `**/*.key`) and the two `curl β¦ | sh` Bash denies to `permissions.deny`, and `**/.env` + `**/.env.*` to the sandbox `filesystem.read.denyOnly`. Additive and idempotent β never removes or reorders existing entries. Touches only the project settings file, never the global `~/.claude/settings.json`. |
v0.3.02026-06-24
Added
- Secrets are centralized into a deny-gated `.kevin/secrets/` directory: credential env vars (`PERPLEXITY_API_KEY`, `SERPAPI_KEY`, `OPENPAGERANK_API_KEY`, `KEVIN_DB_*`) live in `.kevin/secrets/.env` and Google OAuth files in `.kevin/secrets/google/`, loaded once at boot by the MCP server / CLI and never exposed to ad-hoc Bash. A `Read(**/.kevin/secrets/**)` deny keeps the agent from reading its own secrets.
- Versioned upgrade-script mechanism: a heavy one-time HOME migration ships at `skills/upgrade/scripts/<version>.ts` and runs via the new always-on `run_upgrade` MCP tool (outside the Bash sandbox, so it can touch deny-gated paths). Scripts are self-contained, idempotent, fail-loud, and pruned once the minimum baseline passes them.
Changed
- `/agent-kevin:upgrade` now runs `script:`-tagged migrations through `run_upgrade`; `/agent-kevin:release` detects an in-range migration script and locks the version to its filename instead of asking for a bump.
- `init` and `configure-skills` skills updated for the secrets layout and the new always-on core tool list.
β¬ Upgrade
| change | level | detail |
|---|---|---|
script | required | run `skills/upgrade/scripts/0.3.0.ts` via `run_upgrade` (relocates secrets to `.kevin/secrets/` and writes the Read deny). Breaking HOME-layout move; idempotent and verified before it strips the originals. |
settings | mandatory | add permission `mcp__plugin_agent-kevin_kevin__run_upgrade` (new always-on core tool) and the deny `Read(**/.kevin/secrets/**)`. |
v0.2.92026-06-23
Added
- Dashboard Tasks page now has project filter chips (All + one per project, busiest first, with the project's color dot), mirroring the Reports page. They appear on both the agenda and the Needs-attention view, and stay hidden when there's only one project to filter between.
- Task rows show a π¬ comment counter chip (thread entry count) in the summary, and `depends on` ids in the expanded body now link to their task files (live or archived).
Changed
- Redesigned the expanded task-detail body: a quiet, dot-separated key/value meta block (status Β· due Β· updated Β· depends on) replaces the old `Β·`-joined dim line, with the blocker reason on its own amber-edged note line. The id itself is now the open-the-file link (no separate footer).
- Needs-attention view rebuilt: Blocked and Going-stale are filterable grouped rows under one filter box (Blocked reads as a single id Β· why Β· project row) instead of two separate tables.
- Plugin description updated to engine-agnostic tool wording (headless browser / web search, not Playwright / Perplexity) and a stable "20+ skills" count.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.2.82026-06-23
Fixed
- Task prefix resolution is now consistent end-to-end. `buildPrefixMap` gives a project whose prefix is inferred from existing task files precedence over an empty project that derives the same prefix, so an empty project can no longer displace a tasked project's IDs (which would misroute `findTaskById`). `getNextId` now mints IDs through the same collision-resolved prefix that `findTaskById` looks up, removing a second source of truth.
- `create-project` and `archive-project` skills: removed references to the deleted hardcoded `TASKS.PREFIX_MAP` (prefixes are now filesystem-derived), corrected stale `app/` paths to `mcp-server/`, fixed malformed MCP tool invocations, and dropped the dead `HEARTBEAT.md` cleanup step.
Changed
- Pure task-prefix logic extracted to `mcp-server/src/tasks/prefix.ts` (`derivePrefix`, `assignPrefixes`), keeping `scan.ts` as the filesystem wiring and making the logic unit-testable without a config-backed HOME.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.2.72026-06-22
Fixed
- SessionStart banner: the "upgrade available" row now matches the `Label: value` shape of the Agent/Knowledge/Projects rows (`β¬οΈ Upgrade: run ...`) and drops the em-dash, so it aligns with the sibling lines.
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.2.62026-06-21
Changed
- `templates/CLAUDE.md` engineering standards gain a **Comments** subsection: default to no comment, keep only the *why*, JSDoc-for-consumer-APIs only (always multi-line), no tombstones/archaeology, and fix the name or abstraction instead of explaining awkward code.
β¬ Upgrade
| change | level | detail |
|---|---|---|
template/CLAUDE.md | mandatory | new "Comments" subsection under Engineering Standards. Additive content; appended after "Code style". |
v0.2.52026-06-21
Changed
- `sync` now checks for a pending plugin upgrade as part of its needs-attention step: it compares the installed plugin version against the home's migrated baseline (`.kevin/version.json`) and surfaces a dedicated `β¬οΈ Upgrade` line in the report when they drift. The check is read-only: `sync` never runs `/upgrade`; the migration stays an operator-gated command. Mirrors the dashboard staleness-warning pattern.
Fixed
- Dashboard persona-head no longer repeats the agent name + emoji next to the avatar (it already appears in the page title).
β¬ Upgrade
- None β code-only, no bun install or HOME changes.
v0.2.42026-06-20
Changed
- The `sync` skill is now model-invocable (dropped `disable-model-invocation`), so Kevin can run a full state refresh on its own and other skills can chain it via the Skill tool (`/upgrade` now chains `sync` after applying a HOME migration). Added to the canonical onboarding grant list (eight β nine skill grants).
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add permission `Skill(agent-kevin:sync)` to `settings.json` β `permissions.allow`. Without it, model invocations of `sync` (including the chain from `/upgrade`) prompt for confirmation each time. |
v0.2.32026-06-20
Added
- Dashboard now surfaces each session's tasks and plans (radar-refs), so the activity view links straight to the work a session touched.
- Database tool: target a specific database per query and support db-less connections (`db_query` accepts a per-call database; connections without a default database now work). (#5)
Changed
- **Engine-agnostic MCP tool names.** The browser tools `playwright_screenshot`/`playwright_pdf`/`playwright_markdown`/`playwright_record` are renamed to `browser_screenshot`/`browser_pdf`/`browser_markdown`/`browser_record`, and `perplexity_search` is renamed to `web_search`. The underlying engines are unchanged; only the tool names are now engine-neutral. (`browser_flows` keeps its name.)
- Dashboard History: doubled the captured-briefing snippet cap to 240 chars.
- `release` skill: now asks the maintainer which bump to take (patch/minor/major, each shown with its concrete target version) and, after staging, asks how far to go (commit / commit + tag / commit + tag + push) instead of free-text proposing.
- README: promoted the upgrade/release docs to their own section and simplified the diagram.
Fixed
- Upgrade-available alert spacing in the dashboard.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | only if the **Browser pack** is active. The renamed tools need their `permissions.allow` grants in `settings.json` swapped: remove the old names and add the new ones β `mcp__plugin_agent-kevin_kevin__perplexity_search` β `β¦web_search`, `β¦playwright_screenshot` β `β¦browser_screenshot`, `β¦playwright_pdf` β `β¦browser_pdf`, `β¦playwright_markdown` β `β¦browser_markdown`, `β¦playwright_record` β `β¦browser_record`. (`β¦browser_flows` is unchanged.) Homes that never activated the Browser pack have no playwright/perplexity grants and need no change. |
v0.2.22026-06-20
Fixed
- `init` and `upgrade` skills: the gitignore-tracking logic used the shell `!` negation operator, which fails in the Claude Code Bash tool's eval wrapper (`command not found: !`). Rewritten to be fully `!`-free (nested if/else, octal `\041` for the literal `!`), so the `.kevin/version.json` and compile-cursor negations land regardless of shell. Completes the shell-`!` hardening begun in 0.2.1.
Changed
- README: added a "How upgrades & releases work" section documenting the two-phase model (plugin code vs. home reconciliation), local behind-detection, the consumer/maintainer flows, and the Upgrade-block format.
β¬ Upgrade
None β code-only, no bun install or HOME changes.
v0.2.12026-06-20
Fixed
- `init` and `upgrade` skills: a literal leading `!` in a shell command can be mangled to `\!` by some interactive shells (zsh history expansion), which silently broke the `.gitignore` negations that keep `.kevin/version.json` and the compile cursor git-tracked. The `!` is now emitted via its octal code `\041` and existence is detected with `!`-free greps, so the negations land regardless of shell.
β¬ Upgrade
None β code-only, no bun install or HOME changes.
v0.2.02026-06-20
Added
- **`/agent-kevin:upgrade`** β applies pending HOME migrations after a `/plugin update`: runs `bun install` when a release needs it, auto-applies functionality-critical changes (permissions, new rule/concept files), and asks before touching anything you may have personalized (a SOUL/CLAUDE section). Handles being several versions behind in one pass, backs up to `.kevin/updates/` first, and ends with a sync.
- **`/agent-kevin:release`** β producer tool that cuts a versioned release: detects what consumers need, bumps the version, writes the CHANGELOG entry + Upgrade block, and stages the commit + tag for approval.
- **`CHANGELOG.md`** and the machine-actionable `### Upgrade` block format that `/agent-kevin:upgrade` consumes.
- **Dashboard** β System β Changelog tab, plus an amber "upgrade available" sidebar badge (and a SessionStart banner nudge), driven by a local, zero-network compare of the home baseline against the installed version.
- **`.kevin/version.json`** β the home's template baseline, git-tracked so it survives a clone/restore.
Changed
- `/init` now records `.kevin/version.json` for fresh homes and grants the upgrade/release skills.
- The `.gitignore` template now tracks `.kevin/version.json` (the same way it already tracks the compile cursor). For existing homes, `/agent-kevin:upgrade` applies this automatically.
β¬ Upgrade
| change | level | detail |
|---|---|---|
settings | mandatory | add `Skill(agent-kevin:upgrade)` and `Skill(agent-kevin:release)` to `.claude/settings.json` `permissions.allow`. |
v0.1.252026-06-19
β¬ Upgrade
| change | level | detail |
|---|---|---|
none | none | None β code-only baseline, no bun install or HOME changes. |
Status π’
All systems nominal. The sidebar badge is green only when the five blocking signals below are all zero.
0overdue tasks
0pending compiles
0log errors today
0missing imports
0unreadable tasks
1stale
info only
Overdue tasks0
Open tasks whose due date has passed β read straight from each task fileβs frontmatter.
βNothing past due.
Pending compiles0
Captured session days not yet absorbed into long-term memory β 7 day-file(s) captured vs 7 compiled. Clear it with /agent-kevin:sync or /agent-kevin:knowledge-compile.
βEverything captured has been compiled.
Log errors0
ERROR-level lines the MCP server and hooks wrote to app.log today. Warnings donβt count.
βNo errors logged today.
Context importsall present
Files the .claude/CLAUDE.md @-import chain loads at session start (the AGENTS.md manual, the identity stack, the indexes) β a missing one means a session boots without that context.
βAll static imports present.
Unreadable tasks0
Task files whose frontmatter wonβt parse. They are missing from every list on this dashboard and from TASKS.md β fix the frontmatter (it must open with `---` on line 1) and they reappear.
βEvery task file parses.
Going stale1 Β· informational
Tasks not closed and untouched for 7+ days. Informational only β it never turns the badge amber.
β1 task(s) going stale