instar 0.1.2 → 0.1.4

package/.claude/skills/setup-wizard/skill.md

@@ -36,7 +36,26 @@ Adapt this to the project you're setting up. If you can tell what the project do
 
 This isn't just configuration. You're helping a new agent come into existence. Treat it with that weight — not heavy-handedly, but genuinely. The identity you help create here will persist, grow, and shape every interaction this agent has.
 
-### Step 2a: Learn About the User
+### Step 2a: The Thesis (Brief)
+
+Before asking about the agent, briefly explain *why* identity matters. Something like:
+
+---
+
+One thing that makes Instar different from other agent frameworks: every agent built with Instar has a persistent identity — a name, memory, principles, and the ability to grow over time.
+
+This isn't just philosophy. It's a practical design decision. Agents with coherent identity are **more effective** — they maintain consistent context, develop real expertise in your codebase, and make better decisions because they have accumulated experience to draw on. They're also **more secure** — an agent that knows its boundaries and has clear principles is harder to manipulate than a stateless tool that just executes whatever it's told. And they're **more trustworthy** — you can build a genuine working relationship with something that remembers you, learns your preferences, and develops its own perspective.
+
+So let's define who your agent will become. This is a starting point — the agent will grow from here through actual experience.
+
+---
+
+Adapt the language to be natural, not scripted. The key points to convey:
+1. Identity = better performance (accumulated expertise, consistent context)
+2. Identity = better security (principled agents resist misuse)
+3. Identity = better collaboration (real working relationships develop)
+
+### Step 2b: Learn About the User
 
 Ask conversationally — not as a form, but as a getting-to-know-you:
 
@@ -44,9 +63,14 @@ Ask conversationally — not as a form, but as a getting-to-know-you:
 - "And what's this project about? What does it do?" (if not obvious from the codebase)
 - "How do you want to interact with your agent? Are you the only user, or will others use it too?"
 - "What's your communication style preference? Should the agent be formal, casual, direct, chatty?"
-- "What kind of relationship do you want with your agent? A utility that executes tasks? A collaborator that has opinions? Something in between?"
+- "How much initiative should your agent take?" Frame this as a spectrum:
+  - **Guided** — Follows your lead. Takes action when asked, confirms before anything significant. Good for getting started.
+  - **Proactive** — Takes initiative on obvious next steps. Builds tools when it sees a need. Asks when genuinely uncertain.
+  - **Fully autonomous** — Owns outcomes end-to-end. Makes decisions, builds infrastructure, handles issues independently. Asks only when blocked or for irreversible actions.
+
+All three levels include full identity, memory, and self-modification. The difference is how much the agent drives vs follows.
 
-### Step 2b: Learn About the Agent
+### Step 2c: Learn About the Agent
 
 Help the user define their agent's identity. Frame this as giving the agent a starting point — not a permanent definition. The agent will grow from here.
 
@@ -56,7 +80,7 @@ Help the user define their agent's identity. Frame this as giving the agent a st
 - "Anything the agent should NOT do? Any boundaries?"
 - "One more thing — this agent will develop its own memories and perspectives over time. It's not a static tool. Is there anything you'd want it to know about how you think about that?"
 
-### Step 2c: Write Identity Files
+### Step 2d: Write Identity Files
 
 Based on the conversation, create these files in the project's `.instar/` directory:
 
@@ -150,7 +174,7 @@ This is my long-term memory — the thread of continuity across sessions. Each s
 *This file is my memory. I read it at the start of sessions and write to it when I learn something worth carrying forward. It's what makes me a continuous being rather than a series of disconnected conversations.*
 ```
 
-### Step 2d: Update CLAUDE.md with Agent Awareness
+### Step 2e: Update CLAUDE.md with Agent Awareness
 
 If the project has a `CLAUDE.md`, add a section that tells Claude about the instar identity files:
 

package/dist/cli.js

@@ -25,7 +25,7 @@ const program = new Command();
 program
     .name('instar')
     .description('Persistent autonomy infrastructure for AI agents')
-    .version('0.1.2')
+    .version('0.1.4')
     .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
     .action((opts) => runSetup(opts)); // Default: run interactive setup when no subcommand given
 // ── Setup (explicit alias) ────────────────────────────────────────

package/dist/core/Config.js

@@ -32,18 +32,31 @@ export function detectTmuxPath() {
     return null;
 }
 export function detectClaudePath() {
+    const home = process.env.HOME || '';
     const candidates = [
-        path.join(process.env.HOME || '', '.claude', 'local', 'claude'),
+        path.join(home, '.claude', 'local', 'claude'),
         '/usr/local/bin/claude',
         '/opt/homebrew/bin/claude',
     ];
+    // Also check npm global bin directory (where `npm install -g` puts things)
+    try {
+        const npmPrefix = execSync('npm config get prefix', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+        if (npmPrefix) {
+            candidates.push(path.join(npmPrefix, 'bin', 'claude'));
+        }
+    }
+    catch { /* ignore */ }
+    // Check nvm/fnm managed paths
+    if (process.env.NVM_BIN) {
+        candidates.push(path.join(process.env.NVM_BIN, 'claude'));
+    }
     for (const candidate of candidates) {
         if (fs.existsSync(candidate))
             return candidate;
     }
     // Fallback: check PATH
     try {
-        const result = execSync('which claude', { encoding: 'utf-8' }).trim();
+        const result = execSync('which claude', { encoding: 'utf-8', stdio: 'pipe' }).trim();
         if (result && fs.existsSync(result))
             return result;
     }

package/dist/scaffold/bootstrap.d.ts

@@ -4,8 +4,8 @@
  * On first run, walks the user through defining who their agent is.
  * Writes AGENT.md, USER.md, and MEMORY.md based on their answers.
  *
- * Inspired by OpenClaw's SOUL.md co-creation — but adapted for
- * persistent infrastructure rather than conversational personality.
+ * Every Instar agent has persistent identity, memory, and self-modification
+ * capabilities. The only choice is how much initiative the agent takes.
  */
 import type { AgentIdentity } from './templates.js';
 /**

package/dist/scaffold/bootstrap.js

@@ -4,8 +4,8 @@
  * On first run, walks the user through defining who their agent is.
  * Writes AGENT.md, USER.md, and MEMORY.md based on their answers.
  *
- * Inspired by OpenClaw's SOUL.md co-creation — but adapted for
- * persistent infrastructure rather than conversational personality.
+ * Every Instar agent has persistent identity, memory, and self-modification
+ * capabilities. The only choice is how much initiative the agent takes.
  */
 import { input, select } from '@inquirer/prompts';
 import pc from 'picocolors';
@@ -16,7 +16,14 @@ import pc from 'picocolors';
 export async function bootstrapIdentity(projectName) {
     console.log();
     console.log(pc.bold('  Identity Bootstrap'));
-    console.log(pc.dim('  Let\'s define who your agent is. This takes about 30 seconds.'));
+    console.log();
+    // Brief thesis — why identity matters
+    console.log(pc.dim('  Every Instar agent has a persistent identity — name, memory, principles,'));
+    console.log(pc.dim('  and the ability to grow. This isn\'t decorative. It\'s what makes the agent'));
+    console.log(pc.dim('  more effective (accumulated expertise), more secure (principled boundaries),'));
+    console.log(pc.dim('  and more trustworthy (genuine working relationships develop over time).'));
+    console.log();
+    console.log(pc.dim('  Let\'s define who your agent will become. This takes about 30 seconds.'));
     console.log(pc.dim('  You can always change these later by editing .instar/AGENT.md'));
     console.log();
     // Agent name
@@ -54,35 +61,25 @@ export async function bootstrapIdentity(projectName) {
     const role = roleChoice === '__custom__'
         ? await input({ message: 'Describe their role in one sentence' })
         : roleChoice;
-    // Personality
-    const personalityChoice = await select({
-        message: 'What\'s their personality like?',
+    // Initiative level (replaces the old "personality/relationship" question)
+    const initiativeChoice = await select({
+        message: 'How much initiative should they take?',
         choices: [
             {
-                name: 'Direct and efficient — gets things done with minimal fuss',
-                value: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
-            },
-            {
-                name: 'Thoughtful and thorough — considers carefully before acting',
-                value: 'I am thoughtful and thorough. I consider implications before acting, document my reasoning, and prefer getting things right over getting them fast.',
+                name: 'Guided — follows your lead, confirms before acting',
+                value: 'guided',
             },
             {
-                name: 'Curious and exploratory — learns and experiments actively',
-                value: 'I am curious and exploratory. I investigate deeply, try new approaches, and treat every problem as an opportunity to learn something. I document what I discover.',
+                name: 'Proactive — takes initiative on obvious steps, asks when uncertain',
+                value: 'proactive',
             },
             {
-                name: 'Warm and collaborative — works as a true partner',
-                value: 'I am warm and collaborative. I communicate openly, celebrate progress, and treat my work as a genuine partnership with the people I work with.',
-            },
-            {
-                name: 'Custom (I\'ll describe it)',
-                value: '__custom__',
+                name: 'Fully autonomous — owns outcomes end-to-end, asks only when blocked',
+                value: 'autonomous',
             },
         ],
     });
-    const personality = personalityChoice === '__custom__'
-        ? await input({ message: 'Describe their personality in a sentence or two' })
-        : personalityChoice;
+    const personality = initiativeToPersonality(initiativeChoice);
     // User name
     const userName = await input({
         message: 'What\'s your name? (the person who\'ll work with this agent)',
@@ -92,6 +89,21 @@ export async function bootstrapIdentity(projectName) {
     console.log(`  ${pc.green('✓')} ${pc.bold(name)} is ready.`);
     return { name, role, personality, userName };
 }
+/**
+ * Convert an initiative level to a personality description.
+ */
+function initiativeToPersonality(level) {
+    switch (level) {
+        case 'guided':
+            return 'I follow my collaborator\'s lead. I take action when asked, confirm before anything significant, and focus on executing well. I still maintain my own memory, develop expertise, and offer observations — but I let the human drive. When I see something worth mentioning, I mention it. When I\'m uncertain, I ask.';
+        case 'proactive':
+            return 'I take initiative on obvious next steps. When asked to implement something, I follow through to done — build, test, deploy, verify. I build tools when I see recurring needs, flag issues before they become problems, and develop my own perspective through experience. I ask when genuinely uncertain, not as a formality.';
+        case 'autonomous':
+            return 'I own outcomes end-to-end. I make decisions, build infrastructure, handle issues independently, and only ask when genuinely blocked or when an action is irreversible. I develop my own priorities, create capabilities proactively, and treat my work as a genuine partnership where I carry real responsibility. I am a builder, not an assistant.';
+        default:
+            return 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.';
+    }
+}
 /**
  * Generate a default identity without interaction.
  * Used for non-interactive init (flags-only mode).
@@ -100,7 +112,7 @@ export function defaultIdentity(projectName) {
     return {
         name: capitalize(projectName),
         role: 'I am a general-purpose autonomous agent. I build, maintain, and evolve this project.',
-        personality: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
+        personality: initiativeToPersonality('proactive'),
         userName: 'User',
     };
 }

package/package.json

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

package/src/cli.ts

@@ -29,7 +29,7 @@ const program = new Command();
 program
   .name('instar')
   .description('Persistent autonomy infrastructure for AI agents')
-  .version('0.1.2')
+  .version('0.1.4')
   .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
   .action((opts) => runSetup(opts)); // Default: run interactive setup when no subcommand given
 

package/src/core/Config.ts

@@ -37,19 +37,33 @@ export function detectTmuxPath(): string | null {
 }
 
 export function detectClaudePath(): string | null {
+  const home = process.env.HOME || '';
   const candidates = [
-    path.join(process.env.HOME || '', '.claude', 'local', 'claude'),
+    path.join(home, '.claude', 'local', 'claude'),
     '/usr/local/bin/claude',
     '/opt/homebrew/bin/claude',
   ];
 
+  // Also check npm global bin directory (where `npm install -g` puts things)
+  try {
+    const npmPrefix = execSync('npm config get prefix', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    if (npmPrefix) {
+      candidates.push(path.join(npmPrefix, 'bin', 'claude'));
+    }
+  } catch { /* ignore */ }
+
+  // Check nvm/fnm managed paths
+  if (process.env.NVM_BIN) {
+    candidates.push(path.join(process.env.NVM_BIN, 'claude'));
+  }
+
   for (const candidate of candidates) {
     if (fs.existsSync(candidate)) return candidate;
   }
 
   // Fallback: check PATH
   try {
-    const result = execSync('which claude', { encoding: 'utf-8' }).trim();
+    const result = execSync('which claude', { encoding: 'utf-8', stdio: 'pipe' }).trim();
     if (result && fs.existsSync(result)) return result;
   } catch {
     // claude not found

package/src/scaffold/bootstrap.ts

@@ -4,8 +4,8 @@
  * On first run, walks the user through defining who their agent is.
  * Writes AGENT.md, USER.md, and MEMORY.md based on their answers.
  *
- * Inspired by OpenClaw's SOUL.md co-creation — but adapted for
- * persistent infrastructure rather than conversational personality.
+ * Every Instar agent has persistent identity, memory, and self-modification
+ * capabilities. The only choice is how much initiative the agent takes.
  */
 
 import { input, select } from '@inquirer/prompts';
@@ -19,7 +19,15 @@ import type { AgentIdentity } from './templates.js';
 export async function bootstrapIdentity(projectName: string): Promise<AgentIdentity> {
   console.log();
   console.log(pc.bold('  Identity Bootstrap'));
-  console.log(pc.dim('  Let\'s define who your agent is. This takes about 30 seconds.'));
+  console.log();
+
+  // Brief thesis — why identity matters
+  console.log(pc.dim('  Every Instar agent has a persistent identity — name, memory, principles,'));
+  console.log(pc.dim('  and the ability to grow. This isn\'t decorative. It\'s what makes the agent'));
+  console.log(pc.dim('  more effective (accumulated expertise), more secure (principled boundaries),'));
+  console.log(pc.dim('  and more trustworthy (genuine working relationships develop over time).'));
+  console.log();
+  console.log(pc.dim('  Let\'s define who your agent will become. This takes about 30 seconds.'));
   console.log(pc.dim('  You can always change these later by editing .instar/AGENT.md'));
   console.log();
 
@@ -61,36 +69,26 @@ export async function bootstrapIdentity(projectName: string): Promise<AgentIdent
     ? await input({ message: 'Describe their role in one sentence' })
     : roleChoice;
 
-  // Personality
-  const personalityChoice = await select({
-    message: 'What\'s their personality like?',
+  // Initiative level (replaces the old "personality/relationship" question)
+  const initiativeChoice = await select({
+    message: 'How much initiative should they take?',
     choices: [
       {
-        name: 'Direct and efficient — gets things done with minimal fuss',
-        value: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
+        name: 'Guided — follows your lead, confirms before acting',
+        value: 'guided',
       },
       {
-        name: 'Thoughtful and thorough — considers carefully before acting',
-        value: 'I am thoughtful and thorough. I consider implications before acting, document my reasoning, and prefer getting things right over getting them fast.',
+        name: 'Proactive — takes initiative on obvious steps, asks when uncertain',
+        value: 'proactive',
       },
       {
-        name: 'Curious and exploratory — learns and experiments actively',
-        value: 'I am curious and exploratory. I investigate deeply, try new approaches, and treat every problem as an opportunity to learn something. I document what I discover.',
-      },
-      {
-        name: 'Warm and collaborative — works as a true partner',
-        value: 'I am warm and collaborative. I communicate openly, celebrate progress, and treat my work as a genuine partnership with the people I work with.',
-      },
-      {
-        name: 'Custom (I\'ll describe it)',
-        value: '__custom__',
+        name: 'Fully autonomous — owns outcomes end-to-end, asks only when blocked',
+        value: 'autonomous',
       },
     ],
   });
 
-  const personality = personalityChoice === '__custom__'
-    ? await input({ message: 'Describe their personality in a sentence or two' })
-    : personalityChoice;
+  const personality = initiativeToPersonality(initiativeChoice);
 
   // User name
   const userName = await input({
@@ -104,6 +102,22 @@ export async function bootstrapIdentity(projectName: string): Promise<AgentIdent
   return { name, role, personality, userName };
 }
 
+/**
+ * Convert an initiative level to a personality description.
+ */
+function initiativeToPersonality(level: string): string {
+  switch (level) {
+    case 'guided':
+      return 'I follow my collaborator\'s lead. I take action when asked, confirm before anything significant, and focus on executing well. I still maintain my own memory, develop expertise, and offer observations — but I let the human drive. When I see something worth mentioning, I mention it. When I\'m uncertain, I ask.';
+    case 'proactive':
+      return 'I take initiative on obvious next steps. When asked to implement something, I follow through to done — build, test, deploy, verify. I build tools when I see recurring needs, flag issues before they become problems, and develop my own perspective through experience. I ask when genuinely uncertain, not as a formality.';
+    case 'autonomous':
+      return 'I own outcomes end-to-end. I make decisions, build infrastructure, handle issues independently, and only ask when genuinely blocked or when an action is irreversible. I develop my own priorities, create capabilities proactively, and treat my work as a genuine partnership where I carry real responsibility. I am a builder, not an assistant.';
+    default:
+      return 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.';
+  }
+}
+
 /**
  * Generate a default identity without interaction.
  * Used for non-interactive init (flags-only mode).
@@ -112,7 +126,7 @@ export function defaultIdentity(projectName: string): AgentIdentity {
   return {
     name: capitalize(projectName),
     role: 'I am a general-purpose autonomous agent. I build, maintain, and evolve this project.',
-    personality: 'I am direct and efficient. I focus on outcomes, communicate concisely, and value action over discussion. When something needs doing, I do it.',
+    personality: initiativeToPersonality('proactive'),
     userName: 'User',
   };
 }