@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/agent-native-architecture/references/refactoring-to-prompt-native.md

@@ -0,0 +1,342 @@
+<overview>
+How to refactor existing agent code to follow prompt-native principles. The goal: move behavior from code into prompts, and simplify tools into primitives.
+</overview>
+
+<diagnosis>
+## Diagnosing Non-Prompt-Native Code
+
+Signs your agent isn't prompt-native:
+
+**Tools that encode workflows:**
+
+```typescript
+// RED FLAG: Tool contains business logic
+tool("process_feedback", async ({ message }) => {
+  const category = categorize(message);        // Logic in code
+  const priority = calculatePriority(message); // Logic in code
+  await store(message, category, priority);    // Orchestration in code
+  if (priority > 3) await notify();            // Decision in code
+});
+```
+
+**Agent calls functions instead of figuring things out:**
+
+```typescript
+// RED FLAG: Agent is just a function caller
+"Use process_feedback to handle incoming messages"
+// vs.
+"When feedback comes in, decide importance, store it, notify if high"
+```
+
+**Artificial limits on agent capability:**
+
+```typescript
+// RED FLAG: Tool prevents agent from doing what users can do
+tool("read_file", async ({ path }) => {
+  if (!ALLOWED_PATHS.includes(path)) {
+    throw new Error("Not allowed to read this file");
+  }
+  return readFile(path);
+});
+```
+
+**Prompts that specify HOW instead of WHAT:**
+
+```markdown
+// RED FLAG: Micromanaging the agent
+When creating a summary:
+1. Use exactly 3 bullet points
+2. Each bullet must be under 20 words
+3. Format with em-dashes for sub-points
+4. Bold the first word of each bullet
+```
+
+</diagnosis>
+
+<refactoring_workflow>
+
+## Step-by-Step Refactoring
+
+**Step 1: Identify workflow tools**
+
+List all your tools. Mark any that:
+
+- Have business logic (categorize, calculate, decide)
+- Orchestrate multiple operations
+- Make decisions on behalf of the agent
+- Contain conditional logic (if/else based on content)
+
+**Step 2: Extract the primitives**
+
+For each workflow tool, identify the underlying primitives:
+
+| Workflow Tool | Hidden Primitives |
+|---------------|-------------------|
+| `process_feedback` | `store_item`, `send_message` |
+| `generate_report` | `read_file`, `write_file` |
+| `deploy_and_notify` | `git_push`, `send_message` |
+
+**Step 3: Move behavior to the prompt**
+
+Take the logic from your workflow tools and express it in natural language:
+
+```typescript
+// Before (in code):
+async function processFeedback(message) {
+  const priority = message.includes("crash") ? 5 :
+                   message.includes("bug") ? 4 : 3;
+  await store(message, priority);
+  if (priority >= 4) await notify();
+}
+```
+
+```markdown
+// After (in prompt):
+## Feedback Processing
+
+When someone shares feedback:
+1. Rate importance 1-5:
+   - 5: Crashes, data loss, security issues
+   - 4: Bug reports with clear reproduction steps
+   - 3: General suggestions, minor issues
+2. Store using store_item
+3. If importance >= 4, notify the team
+
+Use your judgment. Context matters more than keywords.
+```
+
+**Step 4: Simplify tools to primitives**
+
+```typescript
+// Before: 1 workflow tool
+tool("process_feedback", { message, category, priority }, ...complex logic...)
+
+// After: 2 primitive tools
+tool("store_item", { key: z.string(), value: z.any() }, ...simple storage...)
+tool("send_message", { channel: z.string(), content: z.string() }, ...simple send...)
+```
+
+**Step 5: Remove artificial limits**
+
+```typescript
+// Before: Limited capability
+tool("read_file", async ({ path }) => {
+  if (!isAllowed(path)) throw new Error("Forbidden");
+  return readFile(path);
+});
+
+// After: Full capability
+tool("read_file", async ({ path }) => {
+  return readFile(path);  // Agent can read anything
+});
+// Use approval gates for WRITES, not artificial limits on READS
+```
+
+**Step 6: Test with outcomes, not procedures**
+
+Instead of testing "does it call the right function?", test "does it achieve the outcome?"
+
+```typescript
+// Before: Testing procedure
+expect(mockProcessFeedback).toHaveBeenCalledWith(...)
+
+// After: Testing outcome
+// Send feedback → Check it was stored with reasonable importance
+// Send high-priority feedback → Check notification was sent
+```
+
+</refactoring_workflow>
+
+<before_after>
+
+## Before/After Examples
+
+**Example 1: Feedback Processing**
+
+Before:
+
+```typescript
+tool("handle_feedback", async ({ message, author }) => {
+  const category = detectCategory(message);
+  const priority = calculatePriority(message, category);
+  const feedbackId = await db.feedback.insert({
+    id: generateId(),
+    author,
+    message,
+    category,
+    priority,
+    timestamp: new Date().toISOString(),
+  });
+
+  if (priority >= 4) {
+    await discord.send(ALERT_CHANNEL, `High priority feedback from ${author}`);
+  }
+
+  return { feedbackId, category, priority };
+});
+```
+
+After:
+
+```typescript
+// Simple storage primitive
+tool("store_feedback", async ({ item }) => {
+  await db.feedback.insert(item);
+  return { text: `Stored feedback ${item.id}` };
+});
+
+// Simple message primitive
+tool("send_message", async ({ channel, content }) => {
+  await discord.send(channel, content);
+  return { text: "Sent" };
+});
+```
+
+System prompt:
+
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Generate a unique ID
+2. Rate importance 1-5 based on impact and urgency
+3. Store using store_feedback with the full item
+4. If importance >= 4, send a notification to the team channel
+
+Importance guidelines:
+- 5: Critical (crashes, data loss, security)
+- 4: High (detailed bug reports, blocking issues)
+- 3: Medium (suggestions, minor bugs)
+- 2: Low (cosmetic, edge cases)
+- 1: Minimal (off-topic, duplicates)
+```
+
+**Example 2: Report Generation**
+
+Before:
+
+```typescript
+tool("generate_weekly_report", async ({ startDate, endDate, format }) => {
+  const data = await fetchMetrics(startDate, endDate);
+  const summary = summarizeMetrics(data);
+  const charts = generateCharts(data);
+
+  if (format === "html") {
+    return renderHtmlReport(summary, charts);
+  } else if (format === "markdown") {
+    return renderMarkdownReport(summary, charts);
+  } else {
+    return renderPdfReport(summary, charts);
+  }
+});
+```
+
+After:
+
+```typescript
+tool("query_metrics", async ({ start, end }) => {
+  const data = await db.metrics.query({ start, end });
+  return { text: JSON.stringify(data, null, 2) };
+});
+
+tool("write_file", async ({ path, content }) => {
+  writeFileSync(path, content);
+  return { text: `Wrote ${path}` };
+});
+```
+
+System prompt:
+
+```markdown
+## Report Generation
+
+When asked to generate a report:
+1. Query the relevant metrics using query_metrics
+2. Analyze the data and identify key trends
+3. Create a clear, well-formatted report
+4. Write it using write_file in the appropriate format
+
+Use your judgment about format and structure. Make it useful.
+```
+
+</before_after>
+
+<common_challenges>
+
+## Common Refactoring Challenges
+
+**"But the agent might make mistakes!"**
+
+Yes, and you can iterate. Change the prompt to add guidance:
+
+```markdown
+// Before
+Rate importance 1-5.
+
+// After (if agent keeps rating too high)
+Rate importance 1-5. Be conservative—most feedback is 2-3.
+Only use 4-5 for truly blocking or critical issues.
+```
+
+**"The workflow is complex!"**
+
+Complex workflows can still be expressed in prompts. The agent is smart.
+
+```markdown
+When processing video feedback:
+1. Check if it's a Loom, YouTube, or direct link
+2. For YouTube, pass URL directly to video analysis
+3. For others, download first, then analyze
+4. Extract timestamped issues
+5. Rate based on issue density and severity
+```
+
+**"We need deterministic behavior!"**
+
+Some operations should stay in code. That's fine. Prompt-native isn't all-or-nothing.
+
+Keep in code:
+
+- Security validation
+- Rate limiting
+- Audit logging
+- Exact format requirements
+
+Move to prompts:
+
+- Categorization decisions
+- Priority judgments
+- Content generation
+- Workflow orchestration
+
+**"What about testing?"**
+
+Test outcomes, not procedures:
+
+- "Given this input, does the agent achieve the right result?"
+- "Does stored feedback have reasonable importance ratings?"
+- "Are notifications sent for truly high-priority items?"
+</common_challenges>
+
+<checklist>
+## Refactoring Checklist
+
+Diagnosis:
+
+- [ ] Listed all tools with business logic
+- [ ] Identified artificial limits on agent capability
+- [ ] Found prompts that micromanage HOW
+
+Refactoring:
+
+- [ ] Extracted primitives from workflow tools
+- [ ] Moved business logic to system prompt
+- [ ] Removed artificial limits
+- [ ] Simplified tool inputs to data, not decisions
+
+Validation:
+
+- [ ] Agent achieves same outcomes with primitives
+- [ ] Behavior can be changed by editing prompts
+- [ ] New features could be added without new tools
+</checklist>

package/skills/agent-native-architecture/references/self-modification.md

@@ -0,0 +1,294 @@
+<overview>
+Self-modification is the advanced tier of agent native engineering: agents that can evolve their own code, prompts, and behavior. Not required for every app, but a big part of the future.
+
+This is the logical extension of "whatever the developer can do, the agent can do."
+</overview>
+
+<why_self_modification>
+
+## Why Self-Modification?
+
+Traditional software is static—it does what you wrote, nothing more. Self-modifying agents can:
+
+- **Fix their own bugs** - See an error, patch the code, restart
+- **Add new capabilities** - User asks for something new, agent implements it
+- **Evolve behavior** - Learn from feedback and adjust prompts
+- **Deploy themselves** - Push code, trigger builds, restart
+
+The agent becomes a living system that improves over time, not frozen code.
+</why_self_modification>
+
+<capabilities>
+## What Self-Modification Enables
+
+**Code modification:**
+
+- Read and understand source files
+- Write fixes and new features
+- Commit and push to version control
+- Trigger builds and verify they pass
+
+**Prompt evolution:**
+
+- Edit the system prompt based on feedback
+- Add new features as prompt sections
+- Refine judgment criteria that aren't working
+
+**Infrastructure control:**
+
+- Pull latest code from upstream
+- Merge from other branches/instances
+- Restart after changes
+- Roll back if something breaks
+
+**Site/output generation:**
+
+- Generate and maintain websites
+- Create documentation
+- Build dashboards from data
+</capabilities>
+
+<guardrails>
+## Required Guardrails
+
+Self-modification is powerful. It needs safety mechanisms.
+
+**Approval gates for code changes:**
+
+```typescript
+tool("write_file", async ({ path, content }) => {
+  if (isCodeFile(path)) {
+    // Store for approval, don't apply immediately
+    pendingChanges.set(path, content);
+    const diff = generateDiff(path, content);
+    return { text: `Requires approval:\n\n${diff}\n\nReply "yes" to apply.` };
+  }
+  // Non-code files apply immediately
+  writeFileSync(path, content);
+  return { text: `Wrote ${path}` };
+});
+```
+
+**Auto-commit before changes:**
+
+```typescript
+tool("self_deploy", async () => {
+  // Save current state first
+  runGit("stash");  // or commit uncommitted changes
+
+  // Then pull/merge
+  runGit("fetch origin");
+  runGit("merge origin/main --no-edit");
+
+  // Build and verify
+  runCommand("npm run build");
+
+  // Only then restart
+  scheduleRestart();
+});
+```
+
+**Build verification:**
+
+```typescript
+// Don't restart unless build passes
+try {
+  runCommand("npm run build", { timeout: 120000 });
+} catch (error) {
+  // Rollback the merge
+  runGit("merge --abort");
+  return { text: "Build failed, aborting deploy", isError: true };
+}
+```
+
+**Health checks after restart:**
+
+```typescript
+tool("health_check", async () => {
+  const uptime = process.uptime();
+  const buildValid = existsSync("dist/index.js");
+  const gitClean = !runGit("status --porcelain");
+
+  return {
+    text: JSON.stringify({
+      status: "healthy",
+      uptime: `${Math.floor(uptime / 60)}m`,
+      build: buildValid ? "valid" : "missing",
+      git: gitClean ? "clean" : "uncommitted changes",
+    }, null, 2),
+  };
+});
+```
+
+</guardrails>
+
+<git_architecture>
+
+## Git-Based Self-Modification
+
+Use git as the foundation for self-modification. It provides:
+
+- Version history (rollback capability)
+- Branching (experiment safely)
+- Merge (sync with other instances)
+- Push/pull (deploy and collaborate)
+
+**Essential git tools:**
+
+```typescript
+tool("status", "Show git status", {}, ...);
+tool("diff", "Show file changes", { path: z.string().optional() }, ...);
+tool("log", "Show commit history", { count: z.number() }, ...);
+tool("commit_code", "Commit code changes", { message: z.string() }, ...);
+tool("git_push", "Push to GitHub", { branch: z.string().optional() }, ...);
+tool("pull", "Pull from GitHub", { source: z.enum(["main", "instance"]) }, ...);
+tool("rollback", "Revert recent commits", { commits: z.number() }, ...);
+```
+
+**Multi-instance architecture:**
+
+```
+main                      # Shared code
+├── instance/bot-a       # Instance A's branch
+├── instance/bot-b       # Instance B's branch
+└── instance/bot-c       # Instance C's branch
+```
+
+Each instance can:
+
+- Pull updates from main
+- Push improvements back to main (via PR)
+- Sync features from other instances
+- Maintain instance-specific config
+</git_architecture>
+
+<prompt_evolution>
+
+## Self-Modifying Prompts
+
+The system prompt is a file the agent can read and write.
+
+```typescript
+// Agent can read its own prompt
+tool("read_file", ...);  // Can read src/prompts/system.md
+
+// Agent can propose changes
+tool("write_file", ...);  // Can write to src/prompts/system.md (with approval)
+```
+
+**System prompt as living document:**
+
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Acknowledge warmly
+2. Rate importance 1-5
+3. Store using feedback tools
+
+<!-- Note to self: Video walkthroughs should always be 4-5,
+     learned this from Dan's feedback on 2024-12-07 -->
+```
+
+The agent can:
+
+- Add notes to itself
+- Refine judgment criteria
+- Add new feature sections
+- Document edge cases it learned
+</prompt_evolution>
+
+<when_to_use>
+
+## When to Implement Self-Modification
+
+**Good candidates:**
+
+- Long-running autonomous agents
+- Agents that need to adapt to feedback
+- Systems where behavior evolution is valuable
+- Internal tools where rapid iteration matters
+
+**Not necessary for:**
+
+- Simple single-task agents
+- Highly regulated environments
+- Systems where behavior must be auditable
+- One-off or short-lived agents
+
+Start with a non-self-modifying prompt-native agent. Add self-modification when you need it.
+</when_to_use>
+
+<example_tools>
+
+## Complete Self-Modification Toolset
+
+```typescript
+const selfMcpServer = createSdkMcpServer({
+  name: "self",
+  version: "1.0.0",
+  tools: [
+    // FILE OPERATIONS
+    tool("read_file", "Read any project file", { path: z.string() }, ...),
+    tool("write_file", "Write a file (code requires approval)", { path, content }, ...),
+    tool("list_files", "List directory contents", { path: z.string() }, ...),
+    tool("search_code", "Search for patterns", { pattern: z.string() }, ...),
+
+    // APPROVAL WORKFLOW
+    tool("apply_pending", "Apply approved changes", {}, ...),
+    tool("get_pending", "Show pending changes", {}, ...),
+    tool("clear_pending", "Discard pending changes", {}, ...),
+
+    // RESTART
+    tool("restart", "Rebuild and restart", {}, ...),
+    tool("health_check", "Check if bot is healthy", {}, ...),
+  ],
+});
+
+const gitMcpServer = createSdkMcpServer({
+  name: "git",
+  version: "1.0.0",
+  tools: [
+    // STATUS
+    tool("status", "Show git status", {}, ...),
+    tool("diff", "Show changes", { path: z.string().optional() }, ...),
+    tool("log", "Show history", { count: z.number() }, ...),
+
+    // COMMIT & PUSH
+    tool("commit_code", "Commit code changes", { message: z.string() }, ...),
+    tool("git_push", "Push to GitHub", { branch: z.string().optional() }, ...),
+
+    // SYNC
+    tool("pull", "Pull from upstream", { source: z.enum(["main", "instance"]) }, ...),
+    tool("self_deploy", "Pull, build, restart", { source: z.enum(["main", "instance"]) }, ...),
+
+    // SAFETY
+    tool("rollback", "Revert commits", { commits: z.number() }, ...),
+    tool("health_check", "Detailed health report", {}, ...),
+  ],
+});
+```
+
+</example_tools>
+
+<checklist>
+## Self-Modification Checklist
+
+Before enabling self-modification:
+
+- [ ] Git-based version control set up
+- [ ] Approval gates for code changes
+- [ ] Build verification before restart
+- [ ] Rollback mechanism available
+- [ ] Health check endpoint
+- [ ] Instance identity configured
+
+When implementing:
+
+- [ ] Agent can read all project files
+- [ ] Agent can write files (with appropriate approval)
+- [ ] Agent can commit and push
+- [ ] Agent can pull updates
+- [ ] Agent can restart itself
+- [ ] Agent can roll back if needed
+</checklist>