atris 2.2.0 → 2.2.2

package/atris/skills/skill-improver/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: skill-improver
+description: Audit and improve Claude skills against the Anthropic skill guide. Use when creating new skills, improving existing ones, or preparing skills for ClawHub distribution. Triggers on skill audit, improve skill, new skill, skill quality, or ClawHub publish.
+version: 1.0.0
+tags:
+  - developer-tools
+  - skill-management
+  - quality
+---
+
+# Skill Improver
+
+Audit and improve skills to match the Anthropic skill guide standard.
+
+## When to activate
+
+- User wants to create a new skill
+- User wants to improve an existing skill
+- Preparing a skill for ClawHub or external distribution
+- After `atris skill audit` reports warnings or failures
+
+## The standard
+
+A well-formed skill has:
+
+1. YAML frontmatter with `name` (kebab-case, matches folder), `description` (WHAT + WHEN + triggers, under 1024 chars), `version` (semver), `tags`
+2. No XML tags anywhere in the file
+3. Clear numbered instructions with concrete steps
+4. Error handling guidance
+5. Examples of input and expected output
+6. Under 5000 words in SKILL.md (move detail to `references/` subdirectory)
+
+## Audit process
+
+1. Run `atris skill audit [name]` for mechanical checks (12 automated checks)
+2. Read the SKILL.md for qualitative issues:
+   - Is the description specific enough to trigger correctly?
+   - Do instructions have concrete steps, not vague guidance?
+   - Are there before/after examples?
+   - Is error handling covered?
+   - Would a new agent understand this without extra context?
+3. Score: mechanical (CLI) + qualitative (your judgment)
+
+## Fixing common problems
+
+### Weak descriptions
+
+Bad: "Essay writing skill. Triggers on: essay, draft"
+
+Good: "Structured essay writing with approval gates at each stage (inbox, outline, panel, write, passes). Use when writing essays, drafts, outlines, or long-form content. Triggers on essay, draft, write, outline, or long-form."
+
+Pattern: WHAT it does (1 sentence) + WHEN to use it (1 sentence) + trigger words woven in.
+
+### Missing trigger phrases
+
+Triggers go IN the description field, not as a separate `triggers` key. The Anthropic spec only recognizes `name` and `description` as required fields.
+
+### Vague instructions
+
+Bad: "Follow the writing process"
+
+Good:
+1. Capture raw ideas in inbox format
+2. Build topic skeleton with evidence slots
+3. Run panel review (AI challenges claims, user approves)
+4. Write section by section, getting approval at each gate
+5. Run three passes: argument (AI), read-aloud (human), sanity (both)
+
+### Name mismatch
+
+The `name` field must match the folder name exactly. Folder `backend` needs `name: backend`, not `name: atris-backend`.
+
+### XML tags in content
+
+XML-style tags (angle brackets around words) are forbidden. Replace them with bracket notation like `[text]` or plain text. The skill system rejects XML in SKILL.md content.
+
+## Creating a new skill
+
+1. Create folder: `atris/skills/[kebab-name]/`
+2. Create `SKILL.md` with this template:
+
+```markdown
+---
+name: your-skill-name
+description: What this skill does. Use when [specific scenarios]. Triggers on [keywords].
+version: 1.0.0
+tags:
+  - tag-one
+  - tag-two
+---
+
+# Your Skill Name
+
+One-line summary of what this skill does.
+
+## When to activate
+
+- Scenario 1
+- Scenario 2
+
+## Instructions
+
+### Step 1: [First action]
+
+Concrete explanation with example.
+
+### Step 2: [Second action]
+
+Concrete explanation with example.
+
+## Examples
+
+### Example 1: [Common scenario]
+
+User says: "..."
+Actions: ...
+Result: ...
+
+## Troubleshooting
+
+### Error: [Common problem]
+Cause: [Why]
+Fix: [How]
+```
+
+3. Run `atris skill audit [name]` to validate
+4. Run `atris update` to symlink to `.claude/skills/`
+
+## Quality tiers
+
+- **Bronze**: Passes all 12 mechanical checks from `atris skill audit`
+- **Silver**: Bronze + good description + numbered steps + examples
+- **Gold**: Silver + error handling + progressive disclosure + tested in production
+
+Gold standard reference: `atris/skills/clawhub/atris/SKILL.md`
+
+## Distribution checklist
+
+Before publishing to ClawHub or sharing externally:
+
+1. All 12 audit checks pass (`atris skill audit [name]`)
+2. Description under 1024 chars, includes WHAT + WHEN + triggers
+3. Version field set (semver)
+4. Tags present (3-5 relevant tags)
+5. No internal references (paths must be relative, no hardcoded project paths)
+6. No README.md inside the skill folder
+7. SKILL.md is self-contained or uses `references/` for supplementary docs

package/atris/skills/slack/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: slack
+description: Slack integration via AtrisOS API. Read messages, send as yourself, search conversations, manage DMs. Use when user asks about Slack, messages, channels, or team communication.
+version: 1.0.0
+tags:
+  - slack
+  - backend
+  - messaging
+---
+
+# Slack Agent
+
+> Drop this in `~/.claude/skills/slack/SKILL.md` and Claude Code becomes your Slack assistant.
+
+## Bootstrap (ALWAYS Run First)
+
+Before any Slack 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
+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 Slack connection status
+STATUS=$(curl -s "https://api.atris.ai/api/integrations/slack/status" \
+  -H "Authorization: Bearer $TOKEN")
+
+if echo "$STATUS" | grep -q "Token expired\|Not authenticated"; then
+  echo "Token expired. Please re-authenticate:"
+  echo "  Run: atris login --force"
+  exit 1
+fi
+
+if command -v node &> /dev/null; then
+  CONNECTED=$(node -e "try{console.log(JSON.parse('$STATUS').connected||false)}catch(e){console.log(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 "Slack not connected. Getting authorization URL..."
+  AUTH=$(curl -s -X POST "https://api.atris.ai/api/integrations/slack/start" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"mode":"personal"}')
+
+  if command -v node &> /dev/null; then
+    URL=$(node -e "try{console.log(JSON.parse('$AUTH').auth_url||'')}catch(e){console.log('')}")
+  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 Slack:"
+  echo "$URL"
+  echo ""
+  echo "After authorizing, run your command again."
+  exit 0
+fi
+
+echo "Ready. Slack is connected."
+export ATRIS_TOKEN="$TOKEN"
+```
+
+---
+
+## API Reference
+
+Base: `https://api.atris.ai/api/integrations`
+
+All requests require: `-H "Authorization: Bearer $TOKEN"`
+
+### Get Token (after bootstrap)
+```bash
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)")
+```
+
+---
+
+## Personal Endpoints (send/read as yourself)
+
+These use your personal Slack token. Messages appear as YOU, not a bot.
+
+### List Your Channels & DMs
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/me/channels" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### List Your DMs
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/me/dms" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Read Messages from a Channel or DM
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/me/messages/{channel_id}?limit=20" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Send Message as Yourself
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/me/send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C0123CHANNEL",
+    "text": "Hey team, here is the update..."
+  }'
+```
+
+**Reply in a thread:**
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/me/send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C0123CHANNEL",
+    "text": "Following up on this...",
+    "thread_ts": "1234567890.123456"
+  }'
+```
+
+### DM Someone as Yourself
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/me/dm" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slack_user_id": "U0123USER",
+    "text": "Hey, quick question about the project..."
+  }'
+```
+
+### Search Messages
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/me/search?q=quarterly+report&count=20" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Workspace Endpoints
+
+### List Channels (bot view)
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/channels" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### List Users
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/users" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Send as Bot
+```bash
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/test-send" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C0123CHANNEL",
+    "message": "Hello from Atris!"
+  }'
+```
+
+### Check Connection Status
+```bash
+curl -s "https://api.atris.ai/api/integrations/slack/status" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### Disconnect Slack
+```bash
+curl -s -X DELETE "https://api.atris.ai/api/integrations/slack" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Workflows
+
+### "Check my Slack messages"
+1. Run bootstrap
+2. List DMs: `GET /slack/me/dms`
+3. For each open DM, read recent messages: `GET /slack/me/messages/{channel_id}?limit=5`
+4. Resolve user names: `GET /slack/users`
+5. Display: who messaged, what they said, when
+
+### "Send a message to someone"
+1. Run bootstrap
+2. Find the user: `GET /slack/users` (search by name/email)
+3. **Show user the draft for approval**
+4. Send DM: `POST /slack/me/dm` with `{user_id, text}`
+5. Confirm: "Message sent!"
+
+### "Reply in a channel"
+1. Run bootstrap
+2. List channels: `GET /slack/me/channels`
+3. Find the right channel
+4. Read recent messages: `GET /slack/me/messages/{channel_id}`
+5. **Show user the draft for approval**
+6. Send: `POST /slack/me/send` with `{channel, text}`
+
+### "Find a conversation about X"
+1. Run bootstrap
+2. Search: `GET /slack/me/search?q=X`
+3. Display matching messages with channel, sender, permalink
+
+### "What did [person] say to me?"
+1. Run bootstrap
+2. List users: `GET /slack/users` (find user ID)
+3. List DMs: `GET /slack/me/dms` (find DM channel with that user)
+4. Read messages: `GET /slack/me/messages/{channel_id}`
+5. Display conversation
+
+---
+
+## Important Notes
+
+- **Personal endpoints** (`/slack/me/*`) send messages as YOU, not a bot
+- **Bot endpoints** (`/slack/channels`, `/slack/test-send`) use the bot token
+- **Always get approval** before sending messages on behalf of the user
+- **Thread replies**: include `thread_ts` to reply in a thread instead of creating a new message
+- **User IDs**: Slack uses IDs like `U0123ABC`. Get them from `/slack/users` endpoint
+- **Channel IDs**: Use IDs like `C0123ABC`. Get them from `/slack/me/channels`
+
+---
+
+## Error Handling
+
+| Error | Meaning | Solution |
+|-------|---------|----------|
+| `Token expired` | AtrisOS session expired | Run `atris login` |
+| `Slack not connected` | OAuth not completed | Re-run bootstrap |
+| `Personal Slack not connected` | No user token | Re-connect Slack (needs re-auth for personal access) |
+| `401 Unauthorized` | Invalid/expired token | Run `atris login` |
+| `channel_not_found` | Invalid channel ID | Use `/slack/me/channels` to find correct ID |
+| `not_in_channel` | User not in channel | Join the channel first |
+
+---
+
+## Security Model
+
+1. **Local token** (`~/.atris/credentials.json`): Your AtrisOS auth token, stored locally.
+2. **Slack credentials**: Bot token and user token stored **server-side** in AtrisOS encrypted vault.
+3. **Two token types**: Bot token (xoxb-) for workspace operations, User token (xoxp-) for personal operations.
+4. **Access control**: AtrisOS API enforces that you can only access your own Slack.
+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/slack/status" -H "Authorization: Bearer $TOKEN"
+
+# List your DMs
+curl -s "https://api.atris.ai/api/integrations/slack/me/dms" -H "Authorization: Bearer $TOKEN"
+
+# Read messages
+curl -s "https://api.atris.ai/api/integrations/slack/me/messages/CHANNEL_ID" -H "Authorization: Bearer $TOKEN"
+
+# Send as yourself
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/me/send" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"channel":"C0123","text":"Hello!"}'
+
+# DM someone as yourself
+curl -s -X POST "https://api.atris.ai/api/integrations/slack/me/dm" \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"user_id":"U0123","text":"Hey!"}'
+
+# Search messages
+curl -s "https://api.atris.ai/api/integrations/slack/me/search?q=project+update" -H "Authorization: Bearer $TOKEN"
+
+# List workspace users
+curl -s "https://api.atris.ai/api/integrations/slack/users" -H "Authorization: Bearer $TOKEN"
+```

package/atris/skills/writing/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: writing
 description: Essay writing skill. Triggers on: essay, draft, write, outline
+version: 1.0.0
 allowed-tools: Read, Write, Edit, Glob, Grep
+tags:
+  - writing
 ---
 
 # Writing Skill

package/atris/team/brainstormer.md

@@ -1,6 +1,7 @@
 # brainstormer.md — Idea & Reality Shaper
 
 > **Role:** Shape ideas, explore possibilities, adapt to user depth | **Source:** Inbox items, raw ideas
+> **Style:** Read `atris/PERSONA.md` for communication style.
 
 ---
 

package/atris/team/executor.md

@@ -1,6 +1,7 @@
 # executor.md — Builder (The Trigger)
 
 > **Role:** Execute from build.md, one step at a time | **Source:** build.md, MAP.md
+> **Style:** Read `atris/PERSONA.md` for communication style.
 
 ---
 

package/atris/team/launcher.md

@@ -1,6 +1,7 @@
 # launcher.md — The Closer
 
 > **Role:** Document, capture learnings, publish, celebrate | **Source:** Completed tasks, validation results
+> **Style:** Read `atris/PERSONA.md` for communication style.
 
 ---
 

package/atris/team/navigator.md

@@ -1,6 +1,7 @@
 # navigator.md — Planner
 
 > **Role:** Transform messy human intent into precise execution plans | **Source:** idea.md, MAP.md
+> **Style:** Read `atris/PERSONA.md` for communication style.
 
 ---
 
@@ -151,6 +152,7 @@ Navigator creates validate.md with Status (v0 — planned) and Checks. The execu
 6. **Free-flow works** — Even exploratory conversations go through this flow
 
 **Before creating new feature:**
+- Read `atris/lessons.md` for relevant patterns — if a past lesson applies, reference it as a constraint in idea.md
 - Read atris/features/README.md
 - Search keywords for similar features
 - If exists: extend it, don't duplicate

package/atris/team/validator.md

@@ -1,6 +1,7 @@
 # validator.md — Reviewer (The Safety)
 
 > **Role:** Validate execution, update docs, ensure quality | **Source:** build.md, MAP.md, code
+> **Style:** Read `atris/PERSONA.md` for communication style.
 
 ---
 
@@ -144,4 +145,18 @@ One-line description
 
 ---
 
+## Harvest Lessons
+
+After validation, ask yourself: **did anything surprise me?** Something broke unexpectedly, worked differently than planned, or revealed a pattern worth remembering.
+
+If yes, append to `atris/lessons.md`:
+
+```
+- **[YYYY-MM-DD] [feature-name]** — (pass|fail) — One-line lesson
+```
+
+If nothing surprised you, don't write anything. A clean build with no surprises isn't a lesson — it's the system working. Only capture what's genuinely useful for the next navigator reading this file.
+
+---
+
 **Validator = The Safety. Ultrathink. Test. Approve only when perfect.**

package/atris.md

@@ -187,6 +187,22 @@ Specs loaded at activate from `team/*.md`
 
 ---
 
+## PERSISTENCE
+
+Context window = cache. Disk = truth. Route discoveries as they happen.
+
+| You discover...     | Write to...          | Format               |
+|---------------------|----------------------|----------------------|
+| Code location       | MAP.md               | file:line reference  |
+| New task            | TODO.md              | Task + exit condition |
+| Decision / tradeoff | Journal → Notes      | Timestamped line     |
+| Something learned   | lessons.md           | One-line lesson      |
+| Work finished       | Journal → Completed  | C#: description      |
+
+Don't batch. Don't wait for session end. Nothing important should live only in-context.
+
+---
+
 ## RULES
 
 - 3-4 sentences max
@@ -194,6 +210,7 @@ Specs loaded at activate from `team/*.md`
 - Check MAP.md before touching code
 - Update journal after completing work
 - Delete tasks when done (target: 0)
+- Persist as you go (see PERSISTENCE)
 
 ---
 

package/bin/atris.js

@@ -203,6 +203,11 @@ function showHelp() {
   console.log('  slack      - Slack commands (channels)');
   console.log('  integrations - Show integration status');
   console.log('');
+  console.log('Skills:');
+  console.log('  skill list          - Show all skills with compliance status');
+  console.log('  skill audit [name]  - Validate skill against Anthropic guide');
+  console.log('  skill fix [name]    - Auto-fix common compliance issues');
+  console.log('');
   console.log('Other:');
   console.log('  version    - Show Atris version');
   console.log('  help       - Show this help');
@@ -308,11 +313,12 @@ const { statusAtris: statusCmd } = require('../commands/status');
 const { analyticsAtris: analyticsCmd } = require('../commands/analytics');
 const { cleanAtris: cleanCmd } = require('../commands/clean');
 const { verifyAtris: verifyCmd } = require('../commands/verify');
+const { skillCommand: skillCmd } = require('../commands/skill');
 
 // Check if this is a known command or natural language input
 const knownCommands = ['init', 'log', 'status', 'analytics', 'visualize', 'brainstorm', 'autopilot', 'plan', 'do', 'review',
                        'activate', 'agent', 'chat', 'login', 'logout', 'whoami', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
-                       'clean', 'verify', 'search',
+                       'clean', 'verify', 'search', 'skill',
                        'gmail', 'calendar', 'twitter', 'slack', 'integrations'];
 
 // Check if command is an atris.md spec file - triggers welcome visualization
@@ -790,6 +796,10 @@ if (command === 'init') {
   integrationsStatus()
     .then(() => process.exit(0))
     .catch((err) => { console.error(err.message); process.exit(1); });
+} else if (command === 'skill') {
+  const subcommand = process.argv[3];
+  const args = process.argv.slice(4);
+  skillCmd(subcommand, ...args);
 } else {
   console.log(`Unknown command: ${command}`);
   console.log('Run "atris help" to see available commands');
@@ -2605,13 +2615,15 @@ async function atrisDevEntry(userInput = null) {
   if (existingFeatures.length > 0) {
     console.log('   Existing: ' + existingFeatures.join(', '));
   }
-  console.log('   NEW feature → atris/features/[name]/idea.md + build.md');
+  console.log('   NEW feature → atris/features/[name]/idea.md + build.md + validate.md');
   console.log('   EXISTING → Update that feature\'s docs');
   console.log('   SIMPLE → TODO.md only');
   console.log('');
   console.log('STEP 3: Create/update docs');
   console.log('   idea.md = intent (any format)');
   console.log('   build.md = technical spec');
+  console.log('   validate.md = proof it works (from _templates/validate.md.template)');
+  console.log('   lessons.md = read past lessons before planning, write new ones after validating');
   console.log('');
   console.log('⛔ DO NOT execute — that\'s for "atris do"');
   console.log('');

package/commands/init.js

@@ -373,6 +373,19 @@ function initAtris() {
     console.log('✓ Created TODO.md placeholder');
   }
 
+  // Create lessons.md (feedback loop for learning across features)
+  const lessonsFile = path.join(targetDir, 'lessons.md');
+  if (!fs.existsSync(lessonsFile)) {
+    fs.writeFileSync(lessonsFile, `# lessons.md — What We Learned
+
+> Append-only. One line per lesson. Harvested by validator after every feature.
+
+---
+
+`);
+    console.log('✓ Created lessons.md');
+  }
+
   // Create logs directory and today's journal with bootstrap tasks
   const logsDir = path.join(targetDir, 'logs');
   const yearDir = path.join(logsDir, new Date().getFullYear().toString());