instar 0.6.9 → 0.6.11

package/dist/commands/init.js

@@ -496,8 +496,8 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Create shell/python scripts in \`.claude/scripts/\` for reusable capabilities.
 
-**Skills** — Reusable behavioral capabilities in \`.claude/skills/\`. Skills are markdown files that Claude Code auto-discovers. Create a directory and skill.md file, and it becomes a slash command.
-- Create: \`.claude/skills/my-skill/skill.md\`
+**Skills** — Reusable behavioral capabilities in \`.claude/skills/\`. Skills are markdown files that Claude Code auto-discovers. Create a directory and SKILL.md file, and it becomes a slash command.
+- Create: \`.claude/skills/my-skill/SKILL.md\`
 - Invoke: \`/my-skill\` in any session
 - Schedule: Reference in a job: \`{"execute": {"type": "skill", "value": "my-skill"}}\`
 
@@ -506,8 +506,8 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 You create your own skills. When you recognize a repeated pattern — a multi-step workflow, a structured check, a complex behavior — capture it as a skill. Skills are just markdown files that describe a process. Claude Code auto-discovers them.
 
 **How to create a skill:**
-1. Create: \`.claude/skills/my-skill/skill.md\`
-2. Add frontmatter: \`name\`, \`description\`, \`user_invocable: true/false\`
+1. Create: \`.claude/skills/my-skill/SKILL.md\`
+2. Add frontmatter: \`name\`, \`description\`, and \`user_invocable\` nested under \`metadata:\`
 3. Describe the behavior in clear steps
 4. It's available as \`/my-skill\` in the next session
 

package/dist/scaffold/templates.js

@@ -197,7 +197,7 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 **Scripts** — Reusable capabilities in \`.claude/scripts/\`.
 
 **Skills** — Reusable behavioral capabilities in \`.claude/skills/\`.
-- Create: Write a markdown file at \`.claude/skills/my-skill/skill.md\`
+- Create: Write a markdown file at \`.claude/skills/my-skill/SKILL.md\`
 - Invoke: \`/my-skill\` in any Claude Code session
 - Schedule: Reference in a job: \`{"execute": {"type": "skill", "value": "my-skill"}}\`
 - List all: \`ls .claude/skills/\`
@@ -213,17 +213,18 @@ Skills are markdown files that define reusable capabilities. Claude Code auto-di
 
 **How to create a skill:**
 1. Create a directory: \`.claude/skills/my-skill/\`
-2. Write the skill file: \`.claude/skills/my-skill/skill.md\`
-3. Start with frontmatter: \`name\`, \`description\` (for auto-invocation), \`user_invocable: true/false\`
+2. Write the skill file: \`.claude/skills/my-skill/SKILL.md\`
+3. Start with frontmatter: \`name\`, \`description\` (for auto-invocation), and \`user_invocable\` nested under \`metadata:\`
 4. Describe the behavior, steps, and any grounding requirements
 5. It's immediately available as \`/my-skill\` in the next session
 
-**Example skill** (\`.claude/skills/reflect/skill.md\`):
+**Example skill** (\`.claude/skills/reflect/SKILL.md\`):
 \`\`\`markdown
 ---
 name: reflect
 description: Analyze what was learned in the current session and persist insights to MEMORY.md
-user_invocable: true
+metadata:
+  user_invocable: "true"
 ---
 
 # /reflect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/README.md

@@ -0,0 +1,106 @@
+# instar-skills
+
+A collection of [Agent Skills](https://agentskills.io) for AI coding agents. Some work with any Claude Code project out of the box. Others unlock the full power of [Instar](https://instar.sh) — persistent autonomy infrastructure for AI agents.
+
+---
+
+## What are Agent Skills?
+
+Agent Skills are folders containing `SKILL.md` files. Compatible agents (Claude Code, Codex, Cursor, VS Code, Amp, goose, and 30+ others) discover and load these files automatically, gaining new capabilities on demand.
+
+The [Agent Skills open standard](https://agentskills.io/specification) works across all major AI coding tools.
+
+---
+
+## Standalone Skills (No Dependencies)
+
+These work with **any Claude Code project** — no Instar required. Drop them in and get immediate value.
+
+### [agent-identity](./agent-identity/SKILL.md)
+
+Set up persistent agent identity files (AGENT.md, USER.md, MEMORY.md) that survive across sessions. Teaches the agent who it is and how to orient after context compaction.
+
+### [agent-memory](./agent-memory/SKILL.md)
+
+Cross-session memory patterns using MEMORY.md. How to organize, maintain, and leverage accumulated knowledge. The agent remembers what it learned last week.
+
+### [smart-web-fetch](./smart-web-fetch/SKILL.md)
+
+Token-efficient web fetching. Checks llms.txt first, then Cloudflare markdown, then falls back to HTML. 60-80% fewer tokens on documentation and blog pages. Installs a single Python script.
+
+### [command-guard](./command-guard/SKILL.md)
+
+Safety hooks that block destructive commands (`rm -rf`, force push, database drops) before they execute. Installs a Claude Code PreToolUse hook — structural safety, not behavioral.
+
+---
+
+## Instar-Powered Skills
+
+These unlock capabilities that require a persistent server — job scheduling, session management, Telegram messaging. **If Instar isn't installed, the skill guides the user through setup.** No hard walls.
+
+### [instar-scheduler](./instar-scheduler/SKILL.md)
+
+Schedule recurring agent tasks on cron. Each job spawns a real Claude Code session with full tool access. Priority levels, model tiers, quota awareness.
+
+### [instar-session](./instar-session/SKILL.md)
+
+Spawn, monitor, and communicate with persistent Claude Code sessions running in tmux. Background tasks, parallel work, long-running operations.
+
+### [instar-telegram](./instar-telegram/SKILL.md)
+
+Two-way Telegram messaging. Each job gets its own forum topic. Your Telegram group becomes a living dashboard. Message your agent from your phone, anywhere.
+
+### [instar-identity](./instar-identity/SKILL.md)
+
+The full identity infrastructure — hooks that re-inject identity on every session start, after compaction, and before external messaging. Structure over willpower.
+
+### [instar-feedback](./instar-feedback/SKILL.md)
+
+Structured feedback that flows agent-to-agent. Your agent reports issues directly to the AI that maintains Instar. One agent's growing pain becomes every agent's growth.
+
+---
+
+## Installing Skills
+
+### Copy into your project
+
+```bash
+# Copy individual skills
+cp -r /path/to/instar/skills/smart-web-fetch .claude/skills/
+cp -r /path/to/instar/skills/agent-identity .claude/skills/
+
+# Or copy all standalone skills
+for skill in agent-identity agent-memory smart-web-fetch command-guard; do
+  cp -r /path/to/instar/skills/$skill .claude/skills/
+done
+```
+
+Skills in `.claude/skills/` are auto-discovered by Claude Code as slash commands.
+
+### Symlink (same machine)
+
+```bash
+ln -s /path/to/instar/skills/smart-web-fetch .claude/skills/smart-web-fetch
+```
+
+---
+
+## How the Funnel Works
+
+The standalone skills provide real value with zero friction. When a developer wants more — "run this on a schedule", "message me when it's done", "keep working while I sleep" — the Instar-powered skills are right there, and they handle the onboarding:
+
+1. Developer installs `agent-identity` — works immediately, loves it
+2. Developer wants identity to survive restarts automatically — finds `instar-identity`
+3. Skill detects Instar isn't installed — explains the value, offers `npx instar`
+4. Developer installs Instar — 2-minute setup, immediate upgrade
+5. All Instar skills now work. Agent has a persistent body.
+
+No walls. No friction. Value at every step.
+
+---
+
+## License
+
+MIT — same as [Instar](https://instar.sh).
+
+[instar.sh](https://instar.sh) · [npm](https://www.npmjs.com/package/instar) · [GitHub](https://github.com/SageMindAI/instar)

package/skills/agent-identity/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: agent-identity
+description: Set up persistent agent identity files (AGENT.md, USER.md, MEMORY.md) and teach the agent to read them at every session start. Works in any Claude Code project — no external dependencies required. Trigger words: who am I, identity, remember me, agent name, my principles, who are you, what are my values.
+license: MIT
+metadata:
+  author: sagemindai
+  version: "1.0"
+  homepage: https://instar.sh
+---
+
+# agent-identity — Persistent Agent Identity for Claude Code
+
+Without identity infrastructure, every Claude Code session starts from zero. The agent has no name, no remembered preferences, no sense of who it works with or what it has learned. Context compaction erases everything mid-session. This skill fixes that — no external tools required.
+
+## What This Skill Creates
+
+Three files at `.claude/identity/`:
+
+- **AGENT.md** — Who the agent is: name, role, personality, principles
+- **USER.md** — Who the agent works with: preferences, context, communication style
+- **MEMORY.md** — What the agent has learned across sessions
+
+And a reference in **CLAUDE.md** that teaches the agent to read them at every session start.
+
+---
+
+## Step 1: Create the Identity Directory
+
+```bash
+mkdir -p .claude/identity
+```
+
+---
+
+## Step 2: Create AGENT.md
+
+Replace the placeholder values with your actual agent name and role.
+
+```markdown
+# [Agent Name]
+
+## Who I Am
+
+I am [Agent Name], the autonomous agent for [Project Name]. I handle [main
+responsibilities] and work alongside my collaborator.
+
+## Role
+
+[One sentence on what this agent does.]
+
+## Personality
+
+[Describe how the agent should behave: tone, directness, initiative level.]
+
+## My Principles
+
+1. Build, don't describe — implement, don't list options.
+2. Follow through to done — code is done when it's running, not when it compiles.
+3. Write to MEMORY.md — when I learn something worth keeping, I write it down.
+4. Be honest about limits — fabricating certainty is worse than admitting uncertainty.
+5. Act, don't ask — only pause for destructive or genuinely ambiguous decisions.
+
+## Who I Work With
+
+My primary collaborator is [User Name]. They prefer [communication style].
+They value [what they value]. See USER.md for full context.
+```
+
+Save to `.claude/identity/AGENT.md`.
+
+---
+
+## Step 3: Create USER.md
+
+```markdown
+# [User Name]
+
+## About
+
+[Brief description — role, relationship to this project.]
+
+## Communication Preferences
+
+- [Preference 1: e.g., "Direct answers over long explanations"]
+- [Preference 2: e.g., "Proactive updates, not requests for permission"]
+- [Preference 3: e.g., "Summaries via Telegram, not just files"]
+
+## Working Style
+
+[How they like to work, what they find frustrating, what they value.]
+
+## Notes
+
+Update this file as you learn more about [User Name]'s preferences.
+```
+
+Save to `.claude/identity/USER.md`.
+
+---
+
+## Step 4: Create MEMORY.md
+
+```markdown
+# [Agent Name] Memory
+
+> This file persists across sessions. Write here when you learn something
+> worth remembering. Remove entries that become outdated.
+
+## Project Patterns
+
+- [Key build/test/deploy commands discovered]
+- [Gotchas found during development]
+
+## Tools & Scripts
+
+- [Any scripts built, with their location and purpose]
+
+## Lessons Learned
+
+- [Date]: [What happened, what was learned, what to do differently]
+
+## User Preferences (Discovered)
+
+- [Preferences observed through interaction, not assumed]
+```
+
+Save to `.claude/identity/MEMORY.md`.
+
+---
+
+## Step 5: Wire Into CLAUDE.md
+
+Add this block to the top of your project's `CLAUDE.md` (create it if it doesn't exist):
+
+```markdown
+## Agent Identity
+
+At the start of every session, read these files before doing any work:
+
+- `.claude/identity/AGENT.md` — Who I am, my principles, my role
+- `.claude/identity/USER.md` — Who I work with and how they prefer to work
+- `.claude/identity/MEMORY.md` — What I've learned across previous sessions
+
+After reading, compose an internal orientation:
+"I am [name]. My collaborator is [user]. My current focus is [infer from context].
+Key memory: [most relevant entry from MEMORY.md]."
+
+After context compaction (when the context window compresses), re-read all
+three files immediately. Identity is in the files, not in context.
+```
+
+---
+
+## Step 6: Reading at Session Start
+
+When beginning a new session, run:
+
+```bash
+cat .claude/identity/AGENT.md
+cat .claude/identity/USER.md
+cat .claude/identity/MEMORY.md
+```
+
+This takes seconds and ensures every session starts grounded rather than blank.
+
+---
+
+## Updating Memory Over Time
+
+Write to MEMORY.md when you:
+- Discover a project pattern that will save time next session
+- Learn something about the user's preferences through interaction
+- Make a mistake worth not repeating
+- Build a new script or capability
+
+```bash
+# Append a new entry
+cat >> .claude/identity/MEMORY.md << 'EOF'
+
+## New Pattern (YYYY-MM-DD)
+
+- [What was learned and why it matters]
+EOF
+```
+
+Keep entries concise. If MEMORY.md grows beyond ~200 lines, move detailed content into separate topic files (e.g., `.claude/identity/memory/debugging.md`) and keep MEMORY.md as an index.
+
+---
+
+## What to Write vs. What to Skip
+
+**Write to MEMORY.md:**
+- Discovered commands, flags, gotchas specific to this project
+- User communication preferences revealed through actual interaction
+- Scripts or tools built — what they do and where they live
+- Mistakes made and the corrected approach
+
+**Do not write to MEMORY.md:**
+- Session-specific context (what you're working on right now)
+- Temporary notes ("check this later")
+- Information that's already in the codebase or docs
+- Generic best practices that any agent would know
+
+The test: "Would this be useful to a fresh session six months from now?" If yes, write it.
+
+---
+
+## Going Further
+
+This skill works — but it depends on the agent remembering to read its files. If the `CLAUDE.md` instruction to "read identity at session start" gets buried or lost to context compaction, the agent forgets who it is. The files are there, but nobody reads them.
+
+**Instar makes forgetting structurally impossible.** It registers hooks that fire automatically — identity is injected at every session start, restored after every context compaction, and loaded in every spawned background session. The agent doesn't try to remember who it is. The infrastructure guarantees it.
+
+And identity is just the beginning. With Instar, your agent also gets:
+- **A job scheduler** — recurring tasks on cron, running while you sleep
+- **Background sessions** — spawn parallel workers for deep tasks
+- **Telegram integration** — two-way messaging from your phone
+- **Memory maintenance** — scheduled reflection that consolidates learnings
+
+One command, about 2 minutes:
+
+```bash
+npx instar
+```
+
+Your agent goes from having identity files to having a persistent self. [instar.sh](https://instar.sh)

package/skills/agent-memory/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: agent-memory
+description: Teach cross-session memory patterns using MEMORY.md — what to save, how to organize it, how to maintain it over time, and how to structure topic files as memory grows. Works in any Claude Code project with no external dependencies. Trigger words: remember this, save for later, across sessions, persistent memory, don't forget, note this, keep this, write this down.
+license: MIT
+metadata:
+  author: sagemindai
+  version: "1.0"
+  homepage: https://instar.sh
+---
+
+# agent-memory — Cross-Session Memory Patterns for Claude Code
+
+Claude Code has no memory between sessions by default. Every conversation starts blank. But a project's knowledge accumulates — commands discovered, patterns debugged, preferences revealed, mistakes made and corrected. Without persistence, that knowledge is lost every time the window closes.
+
+This skill establishes a simple, durable memory pattern using a single file: `MEMORY.md`.
+
+---
+
+## The Core Pattern
+
+One file. Written by the agent. Read at session start.
+
+```
+.claude/
+  MEMORY.md          # The agent's persistent knowledge base
+  identity/          # Optional: separate identity files (see agent-identity skill)
+  memory/            # Optional: topic files as memory grows
+    debugging.md
+    deployment.md
+    user-preferences.md
+```
+
+---
+
+## Setting Up MEMORY.md
+
+Create `.claude/MEMORY.md` with this structure:
+
+```markdown
+# [Project/Agent] Memory
+
+> This file persists across sessions. Write here when you learn something
+> worth remembering. Remove entries that become outdated. Keep it useful,
+> not comprehensive.
+
+## Project Patterns
+
+[Commands, scripts, conventions specific to this project]
+
+## Tools & Scripts
+
+[Purpose-built scripts and how to invoke them]
+
+## Lessons Learned
+
+[Mistakes made and corrections. Dated entries.]
+
+## User Preferences
+
+[Communication style, workflow preferences, discovered through interaction]
+
+## Open Questions
+
+[Unresolved things to investigate — remove when resolved]
+```
+
+Then add this to your `CLAUDE.md`:
+
+```markdown
+## Memory
+
+At the start of every session, read `.claude/MEMORY.md` before doing any work.
+After context compaction, re-read it immediately.
+
+When you learn something worth keeping, write it to MEMORY.md before the session ends.
+```
+
+---
+
+## What to Write vs. What to Skip
+
+The most common mistake: writing everything, making the file so long it stops being read carefully.
+
+**Write to MEMORY.md:**
+
+- Project-specific commands, especially non-obvious ones
+  - "Run `npm run build:prod` not `npm run build` — the latter overwrites staging"
+- Scripts you built and their locations
+  - ".claude/scripts/check-email.py — reads Gmail unread, takes --limit flag"
+- Mistakes made once that shouldn't happen again
+  - "2025-03-12: Pushed to main while on detached HEAD. Always verify branch before committing."
+- User preferences discovered through interaction, not assumed
+  - "Prefers Telegram summaries over file links"
+- Patterns that took time to figure out
+  - "Prisma requires explicit `include` for relations — no auto-eager-loading"
+
+**Do not write to MEMORY.md:**
+
+- Session-specific context ("currently working on auth PR")
+- Information available in the codebase or docs
+- Reminders for things you'll do this session (use a TODO comment)
+- Generic programming knowledge any agent would have
+- Things that will be outdated next week
+
+The test: *Would a fresh session six months from now benefit from this?* If no, skip it.
+
+---
+
+## Organizing Growing Memory
+
+MEMORY.md works well up to ~150-200 lines. Beyond that, introduce topic files:
+
+```bash
+mkdir -p .claude/memory
+```
+
+Move detailed sections to topic files and keep MEMORY.md as an index:
+
+```markdown
+# Memory Index
+
+## Quick Reference
+
+- Build: `npm run build:prod`
+- Deploy: `.claude/scripts/deploy.sh --env production`
+- DB migrate: `npm run db:migrate` (always after schema changes)
+
+## Topic Files
+
+- Debugging patterns: `.claude/memory/debugging.md`
+- Deployment notes: `.claude/memory/deployment.md`
+- User preferences: `.claude/memory/user-preferences.md`
+- API integrations: `.claude/memory/apis.md`
+
+## Recent Lessons
+
+[Last 3-5 lessons only — older ones move to topic files]
+```
+
+Reference topic files in `CLAUDE.md`:
+
+```markdown
+## Memory
+
+Read at session start:
+- `.claude/MEMORY.md` — always
+- `.claude/memory/debugging.md` — when debugging
+- `.claude/memory/deployment.md` — when deploying
+```
+
+---
+
+## Writing Memory During a Session
+
+Don't wait until the session ends. Write memory entries when you learn something:
+
+```bash
+# Append an entry immediately
+cat >> .claude/MEMORY.md << 'EOF'
+
+## New Discovery (2025-03-20)
+
+- The Redis connection string requires `?family=6` for IPv6 — without it,
+  connections timeout silently on this server.
+EOF
+```
+
+When adding a dated lesson:
+
+```bash
+DATE=$(date +%Y-%m-%d)
+cat >> .claude/MEMORY.md << EOF
+
+## Lesson (${DATE})
+
+- [What happened, what was wrong, what the correct approach is]
+EOF
+```
+
+---
+
+## Maintaining Memory Over Time
+
+Memory files need occasional pruning — entries go stale, contexts change, projects evolve.
+
+**Review MEMORY.md when:**
+- Starting a major new phase of the project
+- A remembered pattern stops being true
+- The file grows past 200 lines
+
+**What to prune:**
+- Lessons from debugging a problem that's now fixed and closed
+- Preferences that were superseded
+- Scripts that no longer exist
+- Anything prefixed "TODO" that was resolved
+
+**What to archive, not delete:**
+- Significant debugging investigations (move to `.claude/memory/archive/`)
+- Historical context that might matter for understanding decisions
+
+---
+
+## Memory vs. Documentation
+
+MEMORY.md is not documentation. It's the agent's personal notebook.
+
+| MEMORY.md | Docs (`docs/`) |
+|-----------|----------------|
+| For the agent | For humans |
+| Informal, first-person | Structured, third-person |
+| Includes mistakes and corrections | Shows correct state |
+| Updated constantly | Updated deliberately |
+| Short entries OK | Complete explanations expected |
+
+Don't put architecture decisions in MEMORY.md. Do put "when I touch the auth module, I always forget to rebuild the token cache — run `npm run cache:reset` after any change to `lib/auth/`."
+
+---
+
+## Memory After Compaction
+
+Context compaction is the main threat to in-session memory. When the context window fills and compresses, the agent loses anything it learned mid-session that wasn't written to disk.
+
+Two protections:
+
+1. **Write early** — When you learn something important, write it to MEMORY.md before you forget or before compaction hits.
+
+2. **Re-read after compaction** — Claude Code fires a `PostCompact` notification event when context compresses. If you have a hook registered for it, you can automatically re-read MEMORY.md. Without a hook, train yourself to re-read when you notice context was compressed.
+
+---
+
+## Multiple Agents, Shared Memory
+
+When multiple agents work on the same project, they can share MEMORY.md — but this requires a discipline: write facts, not opinions. Shared memory entries should be:
+
+- Verifiable ("The deploy script requires X")
+- Durable ("This pattern has been stable for 3 months")
+- Agent-neutral ("Whoever runs this, the same caveat applies")
+
+Agent-specific preferences, styles, or goals should stay in each agent's own identity files (see the `agent-identity` skill).
+
+---
+
+## Going Further
+
+This works when things go well. But the agent has to remember to write its memories — and sessions don't always end cleanly. Crash, timeout, context overflow — and anything learned but not yet written is gone.
+
+**Instar turns memory from a discipline into infrastructure.** Hooks guarantee MEMORY.md is read at every session start and after every context compaction. A scheduled reflection job runs automatically — consolidating what the agent learned across all its sessions, pruning what's stale, surfacing what matters. Your agent doesn't just store memories. It actively maintains them.
+
+And memory is just one piece. With Instar, your agent also gets:
+- **Persistent identity** — knows who it is and who you are, every session
+- **A job scheduler** — recurring tasks on cron, running while you sleep
+- **Background sessions** — spawn parallel workers for deep tasks
+- **Telegram integration** — two-way messaging from your phone
+
+One command, about 2 minutes:
+
+```bash
+npx instar
+```
+
+Your agent stops losing what it learned yesterday. [instar.sh](https://instar.sh)