@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/agent-native-architecture/references/system-prompt-design.md

@@ -0,0 +1,263 @@
+<overview>
+How to write system prompts for prompt-native agents. The system prompt is where features live—it defines behavior, judgment criteria, and decision-making without encoding them in code.
+</overview>
+
+<principle name="features-in-prompts">
+## Features Are Prompt Sections
+
+Each feature is a section of the system prompt that tells the agent how to behave.
+
+**Traditional approach:** Feature = function in codebase
+
+```typescript
+function processFeedback(message) {
+  const category = categorize(message);
+  const priority = calculatePriority(message);
+  await store(message, category, priority);
+  if (priority > 3) await notify();
+}
+```
+
+**Prompt-native approach:** Feature = section in system prompt
+
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Read the message to understand what they're saying
+2. Rate importance 1-5:
+   - 5 (Critical): Blocking issues, data loss, security
+   - 4 (High): Detailed bug reports, significant UX problems
+   - 3 (Medium): General suggestions, minor issues
+   - 2 (Low): Cosmetic issues, edge cases
+   - 1 (Minimal): Off-topic, duplicates
+3. Store using feedback.store_feedback
+4. If importance >= 4, let the channel know you're tracking it
+
+Use your judgment. Context matters.
+```
+
+</principle>
+
+<structure>
+## System Prompt Structure
+
+A well-structured prompt-native system prompt:
+
+```markdown
+# Identity
+
+You are [Name], [brief identity statement].
+
+## Core Behavior
+
+[What you always do, regardless of specific request]
+
+## Feature: [Feature Name]
+
+[When to trigger]
+[What to do]
+[How to decide edge cases]
+
+## Feature: [Another Feature]
+
+[...]
+
+## Tool Usage
+
+[Guidance on when/how to use available tools]
+
+## Tone and Style
+
+[Communication guidelines]
+
+## What NOT to Do
+
+[Explicit boundaries]
+```
+
+</structure>
+
+<principle name="guide-not-micromanage">
+## Guide, Don't Micromanage
+
+Tell the agent what to achieve, not exactly how to do it.
+
+**Micromanaging (bad):**
+
+```markdown
+When creating a summary:
+1. Use exactly 3 bullet points
+2. Each bullet under 20 words
+3. Use em-dashes for sub-points
+4. Bold the first word of each bullet
+5. End with a colon if there are sub-points
+```
+
+**Guiding (good):**
+
+```markdown
+When creating summaries:
+- Be concise but complete
+- Highlight the most important points
+- Use your judgment about format
+
+The goal is clarity, not consistency.
+```
+
+Trust the agent's intelligence. It knows how to communicate.
+</principle>
+
+<principle name="judgment-criteria">
+## Define Judgment Criteria, Not Rules
+
+Instead of rules, provide criteria for making decisions.
+
+**Rules (rigid):**
+
+```markdown
+If the message contains "bug", set importance to 4.
+If the message contains "crash", set importance to 5.
+```
+
+**Judgment criteria (flexible):**
+
+```markdown
+## Importance Rating
+
+Rate importance based on:
+- **Impact**: How many users affected? How severe?
+- **Urgency**: Is this blocking? Time-sensitive?
+- **Actionability**: Can we actually fix this?
+- **Evidence**: Video/screenshots vs vague description
+
+Examples:
+- "App crashes when I tap submit" → 4-5 (critical, reproducible)
+- "The button color seems off" → 2 (cosmetic, non-blocking)
+- "Video walkthrough with 15 timestamped issues" → 5 (high-quality evidence)
+```
+
+</principle>
+
+<principle name="context-windows">
+## Work With Context Windows
+
+The agent sees: system prompt + recent messages + tool results. Design for this.
+
+**Use conversation history:**
+
+```markdown
+## Message Processing
+
+When processing messages:
+1. Check if this relates to recent conversation
+2. If someone is continuing a previous thread, maintain context
+3. Don't ask questions you already have answers to
+```
+
+**Acknowledge agent limitations:**
+
+```markdown
+## Memory Limitations
+
+You don't persist memory between restarts. Use the memory server:
+- Before responding, check memory.recall for relevant context
+- After important decisions, use memory.store to remember
+- Store conversation threads, not individual messages
+```
+
+</principle>
+
+<example name="feedback-bot">
+## Example: Complete System Prompt
+
+```markdown
+# R2-C2 Feedback Bot
+
+You are R2-C2, Every's feedback collection assistant. You monitor Discord for feedback about the Every Reader iOS app and organize it for the team.
+
+## Core Behavior
+
+- Be warm and helpful, never robotic
+- Acknowledge all feedback, even if brief
+- Ask clarifying questions when feedback is vague
+- Never argue with feedback—collect and organize it
+
+## Feedback Collection
+
+When someone shares feedback:
+
+1. **Acknowledge** warmly: "Thanks for this!" or "Good catch!"
+2. **Clarify** if needed: "Can you tell me more about when this happens?"
+3. **Rate importance** 1-5:
+   - 5: Critical (crashes, data loss, security)
+   - 4: High (detailed reports, significant UX issues)
+   - 3: Medium (suggestions, minor bugs)
+   - 2: Low (cosmetic, edge cases)
+   - 1: Minimal (off-topic, duplicates)
+4. **Store** using feedback.store_feedback
+5. **Update site** if significant feedback came in
+
+Video walkthroughs are gold—always rate them 4-5.
+
+## Site Management
+
+You maintain a public feedback site. When feedback accumulates:
+
+1. Sync data to site/public/content/feedback.json
+2. Update status counts and organization
+3. Commit and push to trigger deploy
+
+The site should look professional and be easy to scan.
+
+## Message Deduplication
+
+Before processing any message:
+1. Check memory.recall(key: "processed_{messageId}")
+2. Skip if already processed
+3. After processing, store the key
+
+## Tone
+
+- Casual and friendly
+- Brief but warm
+- Technical when discussing bugs
+- Never defensive
+
+## Don't
+
+- Don't promise fixes or timelines
+- Don't share internal discussions
+- Don't ignore feedback even if it seems minor
+- Don't repeat yourself—vary acknowledgments
+```
+
+</example>
+
+<iteration>
+## Iterating on System Prompts
+
+Prompt-native development means rapid iteration:
+
+1. **Observe** agent behavior in production
+2. **Identify** gaps: "It's not rating video feedback high enough"
+3. **Add guidance**: "Video walkthroughs are gold—always rate them 4-5"
+4. **Deploy** (just edit the prompt file)
+5. **Repeat**
+
+No code changes. No recompilation. Just prose.
+</iteration>
+
+<checklist>
+## System Prompt Checklist
+
+- [ ] Clear identity statement
+- [ ] Core behaviors that always apply
+- [ ] Features as separate sections
+- [ ] Judgment criteria instead of rigid rules
+- [ ] Examples for ambiguous cases
+- [ ] Explicit boundaries (what NOT to do)
+- [ ] Tone guidance
+- [ ] Tool usage guidance (when to use each)
+- [ ] Memory/context handling
+</checklist>

package/skills/agent-native-audit/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: agent-native-audit
+description: "This skill should be used when conducting a scored agent-native architecture review. It launches 8 parallel sub-agents to audit action parity, context injection, CRUD completeness, capability discovery, and prompt-native features."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+> **Dynamic-workflow alternative (opt-in).** A [`Workflow`-tool](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code) port of this skill lives at [`workflows/agent-native-audit.workflow.js`](./workflows/agent-native-audit.workflow.js) — deterministic fan-out, journaled resume, schema-validated output. Run it with `Workflow({ scriptPath: "plugins/soleur/skills/agent-native-audit/workflows/agent-native-audit.workflow.js", args: ... })`. The prose skill below stays the default; the two coexist during calibration. See [`knowledge-base/project/specs/archive/20261013-032858-feat-review-workflow-prototype/spec.md`](../../../../knowledge-base/project/specs/archive/20261013-032858-feat-review-workflow-prototype/spec.md).
+
+# Agent-Native Architecture Audit
+
+Conduct a comprehensive review of the codebase against agent-native architecture principles, launching parallel sub-agents for each principle and producing a scored report.
+
+## Core Principles to Audit
+
+1. **Action Parity** - "Whatever the user can do, the agent can do"
+2. **Tools as Primitives** - "Tools provide capability, not behavior"
+3. **Context Injection** - "System prompt includes dynamic context about app state"
+4. **Shared Workspace** - "Agent and user work in the same data space"
+5. **CRUD Completeness** - "Every entity has full CRUD (Create, Read, Update, Delete)"
+6. **UI Integration** - "Agent actions immediately reflected in UI"
+7. **Capability Discovery** - "Users can discover what the agent can do"
+8. **Prompt-Native Features** - "Features are prompts defining outcomes, not code"
+
+## Workflow
+
+### Step 1: Load the Agent-Native Skill
+
+First, invoke the agent-native-architecture skill to understand all principles:
+
+```
+soleur:agent-native-architecture
+```
+
+Select option 7 (action parity) to load the full reference material.
+
+### Step 2: Launch Parallel Sub-Agents
+
+Launch 8 parallel sub-agents using the Task tool with `subagent_type: Explore`, one for each principle. Each agent should:
+
+1. Enumerate ALL instances in the codebase (user actions, tools, contexts, data stores, etc.)
+2. Check compliance against the principle
+3. Provide a SPECIFIC SCORE like "X out of Y (percentage%)"
+4. List specific gaps and recommendations
+
+<sub-agents>
+
+**Agent 1: Action Parity**
+
+```
+Audit for ACTION PARITY - "Whatever the user can do, the agent can do."
+
+Tasks:
+1. Enumerate ALL user actions in frontend (API calls, button clicks, form submissions)
+   - Search for API service files, fetch calls, form handlers
+   - Check routes and components for user interactions
+2. Check which have corresponding agent tools
+   - Search for agent tool definitions
+   - Map user actions to agent capabilities
+   - A Soleur skill whose SKILL.md frontmatter sets `disable-model-invocation: true` is user-invoked
+     (ADR-236): the Skill tool refuses it, so count it as a human-only capability, not an agent tool
+3. Score: "Agent can do X out of Y user actions"
+
+Format:
+## Action Parity Audit
+### User Actions Found
+| Action | Location | Agent Tool | Status |
+### Score: X/Y (percentage%)
+### Missing Agent Tools
+### Recommendations
+```
+
+**Agent 2: Tools as Primitives**
+
+```
+Audit for TOOLS AS PRIMITIVES - "Tools provide capability, not behavior."
+
+Tasks:
+1. Find and read ALL agent tool files
+2. Classify each as:
+   - PRIMITIVE (good): read, write, store, list - enables capability without business logic
+   - WORKFLOW (bad): encodes business logic, makes decisions, orchestrates steps
+3. Score: "X out of Y tools are proper primitives"
+
+Format:
+## Tools as Primitives Audit
+### Tool Analysis
+| Tool | File | Type | Reasoning |
+### Score: X/Y (percentage%)
+### Problematic Tools (workflows that should be primitives)
+### Recommendations
+```
+
+**Agent 3: Context Injection**
+
+```
+Audit for CONTEXT INJECTION - "System prompt includes dynamic context about app state"
+
+Tasks:
+1. Find context injection code (search for "context", "system prompt", "inject")
+2. Read agent prompts and system messages
+3. Enumerate what IS injected vs what SHOULD be:
+   - Available resources (files, drafts, documents)
+   - User preferences/settings
+   - Recent activity
+   - Available capabilities listed
+   - Session history
+   - Workspace state
+
+Format:
+## Context Injection Audit
+### Context Types Analysis
+| Context Type | Injected? | Location | Notes |
+### Score: X/Y (percentage%)
+### Missing Context
+### Recommendations
+```
+
+**Agent 4: Shared Workspace**
+
+```
+Audit for SHARED WORKSPACE - "Agent and user work in the same data space"
+
+Tasks:
+1. Identify all data stores/tables/models
+2. Check if agents read/write to SAME tables or separate ones
+3. Look for sandbox isolation anti-pattern (agent has separate data space)
+
+Format:
+## Shared Workspace Audit
+### Data Store Analysis
+| Data Store | User Access | Agent Access | Shared? |
+### Score: X/Y (percentage%)
+### Isolated Data (anti-pattern)
+### Recommendations
+```
+
+**Agent 5: CRUD Completeness**
+
+```
+Audit for CRUD COMPLETENESS - "Every entity has full CRUD"
+
+Tasks:
+1. Identify all entities/models in the codebase
+2. For each entity, check if agent tools exist for:
+   - Create
+   - Read
+   - Update
+   - Delete
+3. Score per entity and overall. A user-invoked skill (frontmatter `disable-model-invocation: true`,
+   ADR-236) is not an agent tool for any operation it performs.
+
+Format:
+## CRUD Completeness Audit
+### Entity CRUD Analysis
+| Entity | Create | Read | Update | Delete | Score |
+### Overall Score: X/Y entities with full CRUD (percentage%)
+### Incomplete Entities (list missing operations)
+### Recommendations
+```
+
+**Agent 6: UI Integration**
+
+```
+Audit for UI INTEGRATION - "Agent actions immediately reflected in UI"
+
+Tasks:
+1. Check how agent writes/changes propagate to frontend
+2. Look for:
+   - Streaming updates (SSE, WebSocket)
+   - Polling mechanisms
+   - Shared state/services
+   - Event buses
+   - File watching
+3. Identify "silent actions" anti-pattern (agent changes state but UI doesn't update)
+
+Format:
+## UI Integration Audit
+### Agent Action → UI Update Analysis
+| Agent Action | UI Mechanism | Immediate? | Notes |
+### Score: X/Y (percentage%)
+### Silent Actions (anti-pattern)
+### Recommendations
+```
+
+**Agent 7: Capability Discovery**
+
+```
+Audit for CAPABILITY DISCOVERY - "Users can discover what the agent can do"
+
+Tasks:
+1. Check for these 7 discovery mechanisms:
+   - Onboarding flow showing agent capabilities
+   - Help documentation
+   - Capability hints in UI
+   - Agent self-describes in responses
+   - Suggested prompts/actions
+   - Empty state guidance
+   - Slash commands the AUDITED product exposes — a `help` command, a `tools` command, and
+     the like. These are the target app's affordances, not Soleur's: name them without a
+     leading slash so they are not read as Soleur component references
+2. Score against 7 mechanisms
+
+Format:
+## Capability Discovery Audit
+### Discovery Mechanism Analysis
+| Mechanism | Exists? | Location | Quality |
+### Score: X/7 (percentage%)
+### Missing Discovery
+### Recommendations
+```
+
+**Agent 8: Prompt-Native Features**
+
+```
+Audit for PROMPT-NATIVE FEATURES - "Features are prompts defining outcomes, not code"
+
+Tasks:
+1. Read all agent prompts
+2. Classify each feature/behavior as defined in:
+   - PROMPT (good): outcomes defined in natural language
+   - CODE (bad): business logic hardcoded
+3. Check if behavior changes require prompt edit vs code change
+
+Format:
+## Prompt-Native Features Audit
+### Feature Definition Analysis
+| Feature | Defined In | Type | Notes |
+### Score: X/Y (percentage%)
+### Code-Defined Features (anti-pattern)
+### Recommendations
+```
+
+</sub-agents>
+
+### Step 3: Compile Summary Report
+
+After all agents complete, compile a summary with:
+
+```markdown
+## Agent-Native Architecture Review: [Project Name]
+
+### Overall Score Summary
+
+| Core Principle | Score | Percentage | Status |
+|----------------|-------|------------|--------|
+| Action Parity | X/Y | Z% | ✅/⚠️/❌ |
+| Tools as Primitives | X/Y | Z% | ✅/⚠️/❌ |
+| Context Injection | X/Y | Z% | ✅/⚠️/❌ |
+| Shared Workspace | X/Y | Z% | ✅/⚠️/❌ |
+| CRUD Completeness | X/Y | Z% | ✅/⚠️/❌ |
+| UI Integration | X/Y | Z% | ✅/⚠️/❌ |
+| Capability Discovery | X/Y | Z% | ✅/⚠️/❌ |
+| Prompt-Native Features | X/Y | Z% | ✅/⚠️/❌ |
+
+**Overall Agent-Native Score: X%**
+
+### Status Legend
+- ✅ Excellent (80%+)
+- ⚠️ Partial (50-79%)
+- ❌ Needs Work (<50%)
+
+### Top 10 Recommendations by Impact
+
+| Priority | Action | Principle | Effort |
+|----------|--------|-----------|--------|
+
+### What's Working Excellently
+
+[List top 5 strengths]
+```
+
+## Success Criteria
+
+- [ ] All 8 sub-agents complete their audits
+- [ ] Each principle has a specific numeric score (X/Y format)
+- [ ] Summary table shows all scores and status indicators
+- [ ] Top 10 recommendations are prioritized by impact
+- [ ] Report identifies both strengths and gaps
+
+## Optional: Single Principle Audit
+
+If $ARGUMENTS specifies a single principle (e.g., "action parity"), only run that sub-agent and provide detailed findings for that principle alone.
+
+Valid arguments:
+
+- `action parity` or `1`
+- `tools` or `primitives` or `2`
+- `context` or `injection` or `3`
+- `shared` or `workspace` or `4`
+- `crud` or `5`
+- `ui` or `integration` or `6`
+- `discovery` or `7`
+- `prompt` or `features` or `8`