From f6f802886809b40975c6f283e53a8b32e8137af2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 23:14:40 +0000 Subject: [PATCH] docs(agents): document the Claude routines that work on this repo Three Claude Code routines act on this repository: two scheduled Vanta routines that triage vulnerabilities into Linear and patch them, and a code review routine fired by code-review.yml. Nothing in the repo said what they do, which repositories and connectors they reach, or which skills they load, so a reviewer seeing their branches and comments had no reference. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KCGEyHS3QLfmsQig8mFEtL --- docs/agents/claude-routines.md | 88 ++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/agents/claude-routines.md diff --git a/docs/agents/claude-routines.md b/docs/agents/claude-routines.md new file mode 100644 index 000000000..28f2e37ad --- /dev/null +++ b/docs/agents/claude-routines.md @@ -0,0 +1,88 @@ +# Claude routines + +Three Claude Code routines work on this repository. Two run on a schedule each +morning and handle dependency vulnerabilities reported by Vanta; the third +reviews pull requests. They run as Claude Code cloud sessions in auto +permission mode, and each loads its skills from +[`cipherstash/skills`](https://github.com/cipherstash/skills). + +1. **vanta-triage** (4:44am Sydney) pulls vulnerabilities from Vanta and files + Linear issues. +2. **vanta-remediate** (5:55am Sydney) picks up those Linear issues, patches + dependencies and opens pull requests. +3. **Code review** runs when a pull request is ready for review and posts a + review. + +## At a glance + +| | vanta-triage | vanta-remediate | Code review | +| --- | --- | --- | --- | +| Trigger | Daily, 4:44am Sydney | Daily, 5:55am Sydney | `.github/workflows/code-review.yml` | +| Skills | `company-skills:vanta-triage` | `company-skills:vanta-remediate` | `/code-review medium`, `company-skills:cross-check-review-findings` | +| Reads | Vanta, Linear | Linear, repositories | The pull request diff and its existing review comments | +| Writes | Linear issues (AppSec project) | Branches, pull requests, Linear status | Inline and summary pull request comments | +| Connectors | Linear, Claude Docs, visualize | Linear, Claude Docs, visualize | Claude Docs, visualize | +| Notifications | Push | Push | Push, email, Slack | +| Repositories | stack, proxy, cipherstash-suite, cipherstash-dynamodb, ore.rs, vitaminc, sqltk, envelopers (8) | Triage's 8, plus skills, docs, cipherstash-js-suite (11) | stack, proxy, cipherstash-suite, cipherstash-dynamodb, ore.rs, vitaminc, skills (7) | + +All repositories are in the `cipherstash` GitHub organization. The lists are +taken from each routine's most recent run. + +## vanta-triage + +Keeps Linear in step with Vanta. It runs `/company-skills:vanta-triage` and +stops with `FAILED` if the skill cannot be loaded from `cipherstash/skills`. + +1. **Connect to Vanta** through the Vanta API credential set on the cloud + environment, not through a routine connector. +2. **Pull vulnerabilities**: Dependabot package alerts and AWS Inspector + container findings, grouped by repository and package. +3. **Cross-check** them against the existing Linear AppSec issues. +4. **Update Linear**: file issues for new findings, retarget issues when Vanta + raises the fix version, and close issues Vanta no longer reports. + +It does not patch code or open pull requests. + +Open question: `cipherstash/skills` is not in triage's repository list, yet its +last run succeeded. Add the repository so skill loading does not depend on a +fallback. + +## vanta-remediate + +Turns triage's Linear issues into pull requests, about an hour after triage. It +runs `/company-skills:vanta-remediate` and stops with `FAILED` if a skill cannot +be loaded. + +1. **Check Linear** for open `[Vanta] Remediate {package} to {version} ({repo})` + issues. +2. **Patch**: find every lockfile that resolves a vulnerable version, bump it + with the repository's package manager, and verify the fix landed. +3. **Open a pull request** on the affected repository and move the Linear issue + to In Review. + +Container OS-package (`[Vanta] Assess`) issues are only assessed on request. It +does not query Vanta or file issues. + +## Code review + +A separate routine with no schedule. `.github/workflows/code-review.yml` fires +it through the routines API when a pull request is opened, reopened or marked +ready for review. Drafts, bot pull requests (Dependabot, release-plz) and forks +are skipped. It reviews once per event, not on every push: mark a pull request +draft and then ready again for a fresh review. + +1. **Review** the pull request with `/code-review medium`. +2. **Cross-check** the findings against existing review feedback with + `company-skills:cross-check-review-findings`, keeping only new ones. +3. **Post** inline comments and a summary comment. The summary names the review + source as an attestation, even when there are no findings, and flags any + blocking issues. + +The workflow needs the `CLAUDE_ROUTINE_TOKEN` secret and the +`CLAUDE_ROUTINE_TRIGGER_ID` variable. The review is advisory: a failed request +shows as a failed step, not a red check. The routine runs in its own cloud +environment, separate from the Vanta routines, and has no Linear access. + +`.github/workflows/claude-review.yml` is a second, CI-based review through +`claude-code-action`. It is off unless the `CLAUDE_REVIEW_ENABLED` variable is +`true`; with both on, a pull request is reviewed twice.