Skip to main content

​
Automatic Attestation Patterns

Learn when and how to automatically create attestations to build a verifiable audit trail of agent work.

​
When to Attest

​
High-Value Triggers

These events should always trigger an attestation:
TriggerWhy It Matters
Git pushPermanent record of code changes
DeploymentProof of what was deployed and when
Database migrationsCritical operations that affect data
Security changesAuth, permissions, encryption modifications
API changesBreaking changes, new endpoints

​
Threshold-Based Triggers

Create attestations when work crosses these thresholds:
  • 3+ files modified - Significant change scope
  • 100+ lines changed - Substantial code modification
  • New dependencies added - Supply chain changes
  • Configuration changes - Environment, secrets, settings

​
Session Milestones

Attest at natural breakpoints:
  • Feature complete - When a requested feature is done
  • Bug fixed - After resolving an issue
  • Refactor complete - After code restructuring
  • Review complete - After code review analysis

​
CLAUDE.md Integration

Add this to your project’s CLAUDE.md: 
## TREESHIP ATTESTATION RULES

### Automatic Triggers
Create an attestation with `treeship_attest` after:

1. **Git Operations**
   - After successful `git push`
   - After creating tags or releases
   - After merging branches

2. **Deployments**
   - After `railway up`, `vercel deploy`, etc.
   - After publishing to npm/PyPI
   - After updating production configs

3. **Significant Changes**
   - 3+ files modified in one task
   - New API endpoints created
   - Database schema changes
   - Security-related modifications

4. **Completions**
   - When user explicitly says "done" or "ship it"
   - After completing a multi-step task
   - Before ending a long session

### Attestation Format

Always include:
- `agent`: Your agent identifier
- `action`: Clear description (what + why)
- `files_modified`: Array of changed files
- `tools_used`: Tools you invoked
- `commit`: Git commit hash (if applicable)

### Example

After pushing auth changes:
treeship_attest( agent=“backend-dev”, action=“Implemented JWT refresh token rotation for security compliance”, summary=“Added automatic token refresh with 7-day sliding window”, files_modified=[“src/auth/tokens.ts”, “src/middleware/auth.ts”], files_created=[“src/auth/refresh.ts”], tools_used=[“Read”, “Write”, “Shell”, “Grep”], commit=“a1b2c3d” )

​
Pattern: Git Hook Attestation

Automatically attest after every push by tracking git operations: 
### Git Workflow

After completing git operations:

1. Stage changes: `git add -A`
2. Commit: `git commit -m "message"`
3. Push: `git push origin branch`
4. **Attest the push:**
treeship_attest( agent=“your-agent”, action=“Pushed: [commit message summary]”, commit=“[commit hash]”, tools_used=[“Shell”] )

​
Pattern: Deploy Attestation

Create deployment receipts: 
### Deployment Workflow

After successful deployment:
treeship_attest( agent=“deploy-agent”, action=“Deployed [service] to [platform]”, summary=“Version X.Y.Z deployed to production”, tools_used=[“Shell”], commit=“[deployed commit]” ) 

Include in summary:
- Service name and version
- Target environment (staging/production)
- Deployment URL
- Any config changes

​
Pattern: Code Review Attestation

Document review findings: 
### Code Review Workflow

After completing a code review:
treeship_attest( agent=“code-reviewer”, action=“Reviewed [PR/feature] - [approval status]”, summary=“[key findings summary]”, files_modified=[], // Reviews don’t modify files tools_used=[“Read”, “Grep”, “Glob”] ) 

Include in summary:
- Number of files reviewed
- Issues found (if any)
- Security concerns
- Performance notes

​
Pattern: Multi-Agent Handoff

When work transfers between agents: 
### Handoff Protocol

**Outgoing Agent:**
treeship_attest( agent=“frontend-agent”, action=“Completed UI components, handing off to backend-agent”, summary=“Created 5 React components, needs API endpoints”, files_created=[“src/components/…”], tools_used=[“Read”, “Write”] ) 

**Incoming Agent:**
First, verify the handoff:
treeship_verify(attestation_id=“[previous attestation id]“) 

Then continue work...

​
Conditional Attestation Logic

Add smart triggers to CLAUDE.md: 
### Attestation Decision Tree

Before ending a task, check:

1. Did I push to git? → Attest
2. Did I deploy anything? → Attest  
3. Did I modify 3+ files? → Attest
4. Did I change security code? → Attest
5. Did the user say "done"? → Attest
6. Has it been 30+ minutes of work? → Attest

If none apply, attestation is optional.

​
Verification Workflow

Always verify before trusting previous work: 
### Verification Protocol

When resuming work or receiving handoffs:

1. Check agent's recent attestations:
treeship_list_attestations(agent=“previous-agent”, limit=5) 

2. Verify specific claims:
treeship_verify(attestation_id=“[id from list]“) 

3. Confirm `valid: true` before proceeding

​
Next Steps