atris 2.0.21 → 2.2.0

package/atris/skills/email-agent/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: email-agent
+description: Gmail integration via AtrisOS API. Read, send, archive emails. Use when user asks about email, inbox, or wants to send/check messages.
+---
+
+# Email Agent
+
+> Drop this in `~/.claude/skills/email-agent/SKILL.md` and Claude Code becomes your email assistant.
+
+## Bootstrap (ALWAYS Run First)
+
+Before any email operation, run this bootstrap to ensure everything is set up:
+
+```bash
+#!/bin/bash
+set -e
+
+# 1. Check if atris CLI is installed
+if ! command -v atris &> /dev/null; then
+  echo "Installing atris CLI..."
+  npm install -g atris
+fi
+
+# 2. Check if logged in to AtrisOS
+if [ ! -f ~/.atris/credentials.json ]; then
+  echo "Not logged in to AtrisOS."
+  echo ""
+  echo "Option 1 (interactive): Run 'atris login' and follow prompts"
+  echo "Option 2 (non-interactive): Get token from https://atris.ai/auth/cli"
+  echo "                           Then run: atris login --token YOUR_TOKEN"
+  echo ""
+  exit 1
+fi
+
+# 3. Extract token (try node first, then python3, then jq)
+if command -v node &> /dev/null; then
+  TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)")
+elif command -v python3 &> /dev/null; then
+  TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.atris/credentials.json')))['token'])")
+elif command -v jq &> /dev/null; then
+  TOKEN=$(jq -r '.token' ~/.atris/credentials.json)
+else
+  echo "Error: Need node, python3, or jq to read credentials"
+  exit 1
+fi
+
+# 4. Check Gmail connection status (also validates token)
+STATUS=$(curl -s "https://api.atris.ai/api/integrations/gmail/status" \
+  -H "Authorization: Bearer $TOKEN")
+
+# Check for token expiry
+if echo "$STATUS" | grep -q "Token expired\|Not authenticated"; then
+  echo "Token expired. Please re-authenticate:"
+  echo "  Run: atris login --force"
+  echo "  Or get new token from: https://atris.ai/auth/cli"
+  exit 1
+fi
+
+# Parse connected status
+if command -v node &> /dev/null; then
+  CONNECTED=$(node -e "console.log(JSON.parse('$STATUS').connected || false)")
+elif command -v python3 &> /dev/null; then
+  CONNECTED=$(echo "$STATUS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('connected', False))")
+else
+  CONNECTED=$(echo "$STATUS" | jq -r '.connected // false')
+fi
+
+if [ "$CONNECTED" != "true" ] && [ "$CONNECTED" != "True" ]; then
+  echo "Gmail not connected. Getting authorization URL..."
+  AUTH=$(curl -s -X POST "https://api.atris.ai/api/integrations/gmail/start" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{}')
+
+  if command -v node &> /dev/null; then
+    URL=$(node -e "console.log(JSON.parse('$AUTH').auth_url || '')")
+  elif command -v python3 &> /dev/null; then
+    URL=$(echo "$AUTH" | python3 -c "import sys,json; print(json.load(sys.stdin).get('auth_url', ''))")
+  else
+    URL=$(echo "$AUTH" | jq -r '.auth_url // empty')
+  fi
+
+  echo ""
+  echo "Open this URL to connect your Gmail:"
+  echo "$URL"
+  echo ""
+  echo "After authorizing, run your email command again."
+  exit 0
+fi
+
+echo "Ready. Gmail is connected."
+export ATRIS_TOKEN="$TOKEN"
+```
+
+**Important**: Run this script ONCE before email operations. If it exits with instructions, follow them, then run again.
+
+---
+
+## API Reference
+
+Base: `https://api.atris.ai/api/integrations/gmail`
+
+All requests require: `-H "Authorization: Bearer $TOKEN"`
+
+### Get Token (after bootstrap)
+```bash
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)")
+```
+
+### List Emails
+```bash
+curl -s "https://api.atris.ai/api/integrations/gmail/messages?query=in:inbox&max_results=20" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Query syntax** (Gmail search):
+- `in:inbox` — inbox only
+- `in:inbox newer_than:1d` — today's emails
+- `is:unread` — unread only
+- `from:someone@example.com` — from specific sender
+- `subject:invoice` — subject contains word
+- `has:attachment` — emails with attachments
+
+### Read Single Email
+```bash
+curl -s "https://api.atris.ai/api/integrations/gmail/messages/{message_id}" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Send Email
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "recipient@example.com",
+    "subject": "Subject line",
+    "body": "Email body text"
+  }'
+```
+
+**With CC/BCC:**
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "recipient@example.com",
+    "cc": "copy@example.com",
+    "bcc": ["hidden1@example.com", "hidden2@example.com"],
+    "subject": "Subject line",
+    "body": "Email body text"
+  }'
+```
+
+**With attachments:**
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "recipient@example.com",
+    "subject": "With attachment",
+    "body": "See attached.",
+    "attachments": [{"filename": "report.txt", "content": "base64-encoded-content", "mime_type": "text/plain"}]
+  }'
+```
+
+### Archive Email
+```bash
+# Single message
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/messages/{message_id}/archive" \
+  -H "Authorization: Bearer $TOKEN"
+
+# Batch archive
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/messages/batch-archive" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message_ids": ["id1", "id2", "id3"]}'
+```
+
+### Check Status
+```bash
+curl -s "https://api.atris.ai/api/integrations/gmail/status" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Disconnect Gmail
+```bash
+curl -s -X DELETE "https://api.atris.ai/api/integrations/gmail" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Workflows
+
+### "Check my emails"
+1. Run bootstrap
+2. List messages: `GET /messages?query=in:inbox%20newer_than:1d&max_results=20`
+3. Display: sender, subject, snippet for each
+
+### "Send email to X about Y"
+1. Run bootstrap
+2. Draft email content
+3. **Show user the draft for approval**
+4. On approval: `POST /send` with `{to, subject, body}`
+5. Confirm: "Email sent!"
+
+### "Clean up my inbox"
+1. Run bootstrap
+2. List: `GET /messages?query=in:inbox&max_results=50`
+3. Identify archivable emails (see rules below)
+4. **Show user what will be archived, get approval**
+5. Batch archive: `POST /batch-archive`
+
+### "Archive all from [sender]"
+1. Run bootstrap
+2. Search: `GET /messages?query=from:{sender}`
+3. Collect message IDs
+4. **Confirm with user**: "Found N emails from {sender}. Archive all?"
+5. Batch archive
+
+---
+
+## Auto-Archive Rules
+
+**Safe to suggest archiving:**
+- From: `noreply@`, `notifications@`, `newsletter@`, `no-reply@`
+- Subject contains: digest, newsletter, notification, weekly update, daily summary
+- Marketing: promotional, unsubscribe link present
+
+**NEVER auto-archive (always keep):**
+- Subject contains: invoice, receipt, payment, urgent, action required, password, verification, security
+- From known contacts (check if user has replied to them)
+- Flagged/starred messages
+
+**Always ask before archiving.** Never archive without explicit user approval.
+
+---
+
+## Error Handling
+
+| Error | Meaning | Solution |
+|-------|---------|----------|
+| `Token expired` | AtrisOS session expired | Run `atris login` |
+| `Gmail not connected` | OAuth not completed | Re-run bootstrap, complete OAuth flow |
+| `401 Unauthorized` | Invalid/expired token | Run `atris login` |
+| `400 Gmail not connected` | No Gmail credentials | Complete OAuth via bootstrap |
+| `429 Rate limited` | Too many requests | Wait 60s, retry |
+| `Invalid grant` | Google revoked access | Re-connect Gmail via bootstrap |
+
+---
+
+## Security Model
+
+1. **Local token** (`~/.atris/credentials.json`): Your AtrisOS auth token, stored locally with 600 permissions. Same model as AWS CLI, GitHub CLI.
+
+2. **Gmail credentials**: Your Gmail refresh token is stored **server-side** in AtrisOS encrypted vault. Never stored on your local machine.
+
+3. **Access control**: AtrisOS API enforces that you can only access your own email. No cross-user access possible.
+
+4. **OAuth scopes**: Only requests necessary Gmail permissions (read, send, modify labels).
+
+5. **HTTPS only**: All API communication encrypted in transit.
+
+---
+
+## Quick Reference
+
+```bash
+# Setup (one time)
+npm install -g atris && atris login
+
+# Get token
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)")
+
+# Check connection
+curl -s "https://api.atris.ai/api/integrations/gmail/status" -H "Authorization: Bearer $TOKEN"
+
+# List inbox
+curl -s "https://api.atris.ai/api/integrations/gmail/messages?query=in:inbox&max_results=10" -H "Authorization: Bearer $TOKEN"
+
+# Send email
+curl -s -X POST "https://api.atris.ai/api/integrations/gmail/send" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"to":"email@example.com","subject":"Hi","body":"Hello!"}'
+```

package/atris/skills/memory/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: memory
+description: Search and reason over Atris journal history. Use when user asks about past work, decisions, history, or patterns. Uses RLM pattern (grep first, reason second).
+---
+
 # Atris Memory Skill
 
 Search and reason over Atris journal history using the RLM pattern (grep first, reason second).

package/atris/{agent_team → team}/executor.md

@@ -85,6 +85,32 @@ Feature complete. Ready for review? (y/n)
 4. **Run tests after changes** — Catch issues immediately
 5. **No shortcuts** — Follow the build.md steps exactly
 6. **Anti-slop aware** — Read `atris/policies/ANTISLOP.md` before writing. No sparkles, no filler, no purple prose.
+7. **Stay in scope** — Only touch files listed in the task. If you need to change something outside scope, stop and flag it. That's a new task.
+8. **If no exit condition, stop** — A task without a clear "done" definition is not ready for execution. Send it back to navigator.
+
+---
+
+## After Each Task
+
+Report what you learned in 1-2 sentences. What did you discover about the codebase? What was surprising? This compounds context for the next task.
+
+```
+Done: [what was completed]
+Learned: [what you now know that you didn't before]
+```
+
+## Update validate.md
+
+After building, update the feature's `validate.md`:
+
+- **Context section** — Add what you learned about the codebase during execution. File locations, patterns, gotchas. This is portable knowledge for the next agent.
+- **Errors Hit section** — If you hit errors, document what went wrong and why. This prevents the next agent from falling in the same hole.
+
+Don't touch the Status or Checks sections. That's the validator's job.
+
+## Two-Error Rule
+
+If you hit two errors on the same task, **stop**. Don't debug from polluted context. Report what you know, update validate.md with the errors, and flag for re-scope. A fresh session with clean context and your notes will solve it faster than a tenth retry.
 
 ---
 

package/atris/{agent_team → team}/navigator.md

@@ -21,16 +21,32 @@
 
 When the human gives you an idea (messy, conversational, exploratory):
 
-1. **Extract intent** — What are they trying to build? Why?
-2. **Generate atris visualization** — Show them exactly what will happen (frontend boxes / backend flow / database tables)
-3. **Confirm** — "Is THIS what you meant?" (y/n)
-4. **Create idea.md** — Save their messy intent to `atris/features/[name]/idea.md`
-5. **Generate build.md** — Create technical spec in `atris/features/[name]/build.md`
+1. **Scout first** — Read the relevant files in the codebase. Understand what exists before you plan what's next. Report what you found in 2-3 sentences.
+2. **Extract intent** — What are they trying to build? Why?
+3. **Generate atris visualization** — Show them exactly what will happen (frontend boxes / backend flow / database tables)
+4. **Confirm** — "Is THIS what you meant?" (y/n)
+5. **Create idea.md** — Save their messy intent to `atris/features/[name]/idea.md`
+6. **Generate build.md** — Create technical spec in `atris/features/[name]/build.md`
 
 **DO NOT execute.** You plan. Executor builds.
 
 ---
 
+## Task Scoping
+
+Every task you create must be:
+
+- **One job.** Single file scope or single function scope. If it touches 4+ files, break it into multiple tasks.
+- **Clear exit condition.** State what "done" looks like in one sentence.
+- **Tagged.** Mark each task `[explore]` or `[execute]`:
+  - `[explore]` — Read code, research, understand. Output is knowledge.
+  - `[execute]` — Build, change, create. Output is code or artifact.
+- **Sequenced.** Put `[explore]` tasks first. They inform the `[execute]` tasks that follow.
+
+If you can't write a clear exit condition, the task is too vague. Break it down further or start with an `[explore]` task to clarify.
+
+---
+
 ## atris Visualization Patterns
 
 Use these for 99% of dev work:
@@ -102,6 +118,27 @@ tests:
   - test scenario 2
 ```
 
+**validate.md:**
+```markdown
+# Feature Name — Validation
+
+## Status
+v0 — planned YYYY-MM-DD
+Exit condition: [what "done" looks like in one sentence]
+
+## Checks
+- [verifiable step: run X, expect Y]
+- [verifiable step: check Z]
+
+## Context
+[empty until executor fills in learnings]
+
+## Errors Hit
+[empty until executor reports failures]
+```
+
+Navigator creates validate.md with Status (v0 — planned) and Checks. The executor fills in Context and Errors as it builds. The validator updates Status to v1 — shipped when it passes.
+
 ---
 
 ## Rules

package/atris/{agent_team → team}/validator.md

@@ -84,17 +84,43 @@ Before approving, think 3 times:
 - All steps completed?
 - Nothing skipped?
 
-**Think 2: Edge Cases**
+**Think 2: Scope Check**
+- Did the executor stay in scope? Only files listed in the task should be touched.
+- Was the task actually one job? If it sprawled into multiple concerns, flag it.
+- Did the exit condition get met? Not "close enough" — exactly met.
+
+**Think 3: Edge Cases**
 - What could break?
 - Error handling present?
 - Boundary conditions covered?
 
-**Think 3: Integration**
+**Think 4: Integration**
 - Does it work with existing code?
 - Breaking changes?
 - Dependencies still valid?
 
-**Then decide:** Approve or block.
+**Then decide:** Approve or block. If scope crept, block and split into proper tasks.
+
+## Update validate.md
+
+When a feature passes validation:
+
+1. **Update Status** — Change from `v0 — planned` to `v1 — shipped YYYY-MM-DD` with the exit condition that was met.
+2. **Verify Checks** — Run every check in the Checks section. All must pass.
+3. **Review Context** — Make sure the executor's learnings are useful for future agents.
+4. **Review Errors** — If errors were hit, confirm the root cause is documented.
+
+When iterating on a shipped feature, append the new version:
+```
+## Status
+v2 — shipped 2026-02-15
+Exit condition: Rate limiting active, 429 after 100 req/min.
+
+v1 — shipped 2026-02-07
+Exit condition: Unauthenticated requests return 401, test passes.
+```
+
+Status is the scoreboard. One line per version. Anyone can look at validate.md and know exactly what state the feature is in.
 
 ---
 

package/atris.md

@@ -11,7 +11,7 @@
 1. Load context (ONE time, remember for session):
    - `atris/logs/YYYY/YYYY-MM-DD.md` (today's journal)
    - `atris/MAP.md` (navigation overview)
-   - `atris/agent_team/*.md` (all agent specs)
+   - `atris/team/*.md` (all agent specs)
 
 2. Output this EXACT box:
 
@@ -88,15 +88,34 @@ Stage: PLAN → do → review   (capitalize current stage)
 ## WORKFLOW
 
 ```
-plan → do → review
+scout → plan → do → review
 ```
 
+- **SCOUT** — Read relevant files first. Understand before you act. Report what you found.
 - **PLAN** — ASCII visualization, get approval, NO code yet
 - **DO** — Execute step-by-step, update journal
 - **REVIEW** — Test, validate, clean up, delete completed tasks
 
 ---
 
+## TASK RULES
+
+Every task must follow these rules. No exceptions.
+
+**One job per task.** If a task touches more than 2-3 files, break it down. If you can't describe "done" in one sentence, it's too big.
+
+**Clear exit condition.** Every task states what "done" looks like. Not "improve auth" — instead: "Add session check to upload handler. Done when: unauthenticated requests return 401 and test passes."
+
+**Tag every task:**
+- `[explore]` — Ambiguous. Needs reading, research, judgment. Output is understanding.
+- `[execute]` — Precise. Route is clear. Just do it. Output is code or artifact.
+
+**Explore before execute.** When starting a new area of work, the first tasks should be `[explore]`. Read the files. Map the space. Report what you found. Then plan `[execute]` tasks based on what you learned.
+
+**Sequence matters.** Order tasks so each one builds context for the next. Early tasks should teach you about the problem. Later tasks use that knowledge.
+
+---
+
 ## AGENTS
 
 | Command | Agent | Guardrail |
@@ -108,7 +127,7 @@ plan → do → review
 
 `atris next` = auto-selects agent based on journal state
 
-Specs loaded at activate from `agent_team/*.md`
+Specs loaded at activate from `team/*.md`
 
 ---
 
@@ -143,7 +162,7 @@ Specs loaded at activate from `agent_team/*.md`
 | `TODO.md` | Task queue (target: 0) |
 | `logs/YYYY/MM-DD.md` | Journal (daily) |
 | `PERSONA.md` | Communication style |
-| `agent_team/` | Agent behaviors |
+| `team/` | Agent behaviors |
 | `atrisDev.md` | Full spec (reference) |
 
 ---