liteagents 2.4.6 → 2.5.0

package/packages/droid/commands/friction.md

@@ -0,0 +1,139 @@
+---
+name: friction
+description: Analyze session behavior patterns
+usage: /friction <sessions-path>
+argument-hint: <sessions-path>
+---
+
+Analyze Claude Code session logs for friction signals, behavioral patterns, and failure antigens.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**Argument: sessions-path (required)**
+
+Path to the Droid sessions directory containing JSONL files.
+- Example: `/friction ~/.factory/projects/-home-hamr-PycharmProjects-aurora/`
+- If no argument provided, ask the user for the path. Do NOT guess.
+
+**What it does**
+
+Runs friction analysis on session JSONL files and writes results to `.factory/friction/` in the current project.
+
+**Steps**
+
+1. **Validate path**
+   - The argument `$ARGUMENTS` is the sessions path
+   - Verify the path exists and contains `.jsonl` files
+   - If path doesn't exist or has no JSONL files, tell the user and stop
+   - Count total session files found
+
+2. **Run friction.js** (bundled at `commands/friction/friction.js`)
+   - Look for friction.js in order:
+     1. `~/.factory/commands/friction/friction.js` (installed)
+     2. `packages/droid/commands/friction/friction.js` (package development)
+   - If found, run: `node <path-to-friction.js> "$ARGUMENTS"`
+   - If it does NOT exist anywhere, fall back to running the analysis manually (step 3)
+   - If friction.js succeeds, skip to step 7
+
+3. **Manual analysis fallback** (only if friction.js not available)
+   - For each `.jsonl` session file in the path:
+     - Read the file
+     - Extract signals using these patterns:
+
+   | Signal | Weight | How to detect |
+   |---|---|---|
+   | `user_intervention` | 10 | User message contains `/stash` |
+   | `session_abandoned` | 10 | Last 3 turns have friction > 15 and no `exit_success` |
+   | `false_success` | 8 | LLM text contains "done"/"complete"/"fixed" AND next tool result has error |
+   | `no_resolution` | 8 | Session has `exit_error` signals but no `exit_success` after them |
+   | `tool_loop` | 6 | Same tool called 3+ times with identical arguments |
+   | `rapid_exit` | 6 | <3 turns AND ends with error |
+   | `interrupt_cascade` | 5 | Multiple `request_interrupted` within 60 seconds |
+   | `user_curse` | 5 | User message matches profanity patterns |
+   | `request_interrupted` | 2.5 | Turn has `is_interrupted: true` or ESC/Ctrl+C signal |
+   | `exit_error` | 1 | Tool result has non-zero exit code |
+   | `repeated_question` | 1 | User asks same question twice (fuzzy match) |
+   | `long_silence` | 0.5 | >10 minute gap between turns |
+   | `user_negation` | 0.5 | User message starts with "no", "wrong", "didn't work" |
+   | `compaction` | 0.5 | System message indicates context compaction |
+
+4. **Score each session**
+   - Accumulate weighted signal scores (no subtraction, only accumulation)
+   - Track peak friction score
+   - Classify session quality:
+     - **BAD**: has `user_intervention` or `session_abandoned`
+     - **FRICTION**: has `user_curse` or `false_success`
+     - **ROUGH**: peak friction >= 15, no intervention
+     - **OK**: low friction, completed normally
+     - **ONE-SHOT**: single turn, not interactive (filter out)
+
+5. **Aggregate stats**
+   - Count sessions by quality
+   - Calculate BAD rate
+   - Identify worst and best sessions
+   - Daily trend if sessions span multiple days
+
+6. **Extract antigen candidates from BAD sessions**
+   - For each BAD session, extract:
+     - Anchor signal (what triggered BAD classification)
+     - Tool sequence around the failure
+     - Error messages
+     - Pattern description
+   - Write as antigen candidates
+
+7. **Write output to `.factory/friction/`**
+   - Create `.factory/friction/` directory if it doesn't exist
+   - Write these files:
+     - `friction_analysis.json` — per-session breakdown (quality, peak, signals)
+     - `friction_summary.json` — aggregate stats, verdict, daily trend
+     - `friction_raw.jsonl` — all raw signals with timestamps
+     - `antigen_candidates.json` — raw extracted failure patterns
+     - `antigen_clusters.json` — clustered patterns (primary artifact for /remember)
+     - `antigen_review.md` — human-readable clustered review
+
+8. **Report to user**
+   - Sessions analyzed count
+   - BAD / FRICTION / ROUGH / OK counts
+   - BAD rate percentage
+   - Worst session ID and peak friction
+   - Path to `antigen_review.md` for review
+   - Remind: run `/remember` to consolidate into project memory
+
+**Output format for antigen_review.md**
+
+```markdown
+# Friction Antigen Clusters
+
+Generated: [date]
+BAD sessions: [count] | Raw candidates: [count] | Clusters: [count]
+
+## Cluster Summary
+
+| # | Signal | Tool Pattern | Count | Sessions | Score | Median Peak |
+|---|--------|-------------|-------|----------|-------|-------------|
+| 1 | false_success | Bash,Bash | 35 | 23 | 280 | 73 |
+| 2 | user_intervention | (none) | 34 | 24 | 340 | 65 |
+
+## Cluster 1: false_success | Bash,Bash
+
+**Occurrences:** 35 across 23 sessions | **Score:** 280
+
+### User Context (what the user said)
+> [actual user quote from session]
+
+### Errors
+[error messages if any]
+
+### Files involved
+- [file paths]
+```
+
+**File locations**
+- Design doc: `docs/02-features/memory/LONG_TERM_MEMORY.md`
+- Input: JSONL session files from `$ARGUMENTS` path
+- Output: `.factory/friction/` (project-local)
+- JS script: `commands/friction/friction.js` (bundled alongside this command)
+- Python equivalent: `scripts/friction.py` (aurora users, same logic)
+- Manual fallback: built into this command if friction.js unavailable

package/packages/droid/commands/remember.md

@@ -0,0 +1,110 @@
+---
+name: remember
+description: Consolidate stashes + friction into project memory
+usage: /remember
+---
+
+Consolidate session stashes and friction analysis into a single project-local MEMORY.md, then inject into AGENTS.md.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**What it does**
+
+Reads all raw material (`.factory/stash/*.md` + `.factory/friction/antigen_clusters.json`), extracts durable facts, episodes, and behavioral preferences into a single `.factory/memory/MEMORY.md`, then injects a managed memory section into `AGENTS.md`.
+
+**Steps**
+
+1. **Gather sources**
+   - Read all `.factory/stash/*.md` files in the current project
+   - Check for friction output at `.factory/friction/antigen_clusters.json` (preferred) or `.factory/friction/antigen_review.md` (fallback)
+   - Read existing `.factory/memory/MEMORY.md` if it exists — create dir if missing
+   - Read processed manifest at `.factory/memory/.processed` — skip already-processed stashes
+   - If no unprocessed stashes, report "nothing to consolidate" and stop
+
+2. **Extract from unprocessed stashes** (use Task tool with sonnet model for each)
+   - For each unprocessed stash, call sonnet to extract:
+     - **FACTS** (atomic, one-line): stable preferences, decisions, corrections, explicit "remember this"
+     - **EPISODE** (3-5 bullet narrative): what was the goal, what was tried, outcome, lesson
+     - **SKIP**: code details, file paths, errors, mechanical steps, LLM responses
+   - Collect all new facts and episodes
+
+3. **Merge into MEMORY.md**
+   - Read existing `.factory/memory/MEMORY.md` and parse its three sections (## Facts, ## Episodes, ## Preferences)
+   - **Facts section**: call sonnet with existing facts + newly extracted facts
+     - Rules: new updates replace old, contradictions keep new version, duplicates dropped
+     - Keep facts atomic, one line each
+   - **Episodes section**: append new episode entries (append-only, timestamped, no dedup)
+   - **Preferences section**: only update if friction output exists (step 4)
+   - Write merged result to `.factory/memory/MEMORY.md` in this format:
+
+   ```markdown
+   # Project Memory
+   > Auto-generated by /remember. Do not edit manually.
+
+   ## Facts
+   - [atomic fact 1]
+   - [atomic fact 2]
+
+   ## Episodes
+   ### YYYY-MM-DD - [title]
+   - [bullet narrative]
+
+   ### YYYY-MM-DD - [title]
+   - [bullet narrative]
+
+   ## Preferences
+   ### High Confidence
+   - [pattern] (evidence: [count] observations)
+
+   ### Medium Confidence
+   - [pattern] (evidence: [count] observations)
+
+   ### Low Confidence
+   - [pattern] (evidence: [count] observations)
+   ```
+
+4. **Distill friction into preferences** (only if friction output exists)
+   - Read `.factory/friction/antigen_clusters.json` — this contains clustered failure patterns with counts, user_context quotes, and tool sequences
+   - For the **top 10 clusters** (by score), extract the `contexts` field — these are the actual user messages that show behavioral patterns
+   - Call sonnet with:
+     - The top 10 clusters (signal, tool_pattern, count, sessions, contexts, errors)
+     - Existing Preferences section from MEMORY.md
+   - Extract BEHAVIORAL preferences (patterns demonstrated, not stated) — the user_context quotes are the primary evidence
+   - Confidence tiers:
+     - **High Confidence**: 5+ observations — available via @MEMORY.md
+     - **Medium Confidence**: 3+ observations — observing, not loaded
+     - **Low Confidence**: <3 observations — needs more data
+   - Promote/demote based on new evidence
+   - Update the Preferences section in MEMORY.md
+
+5. **Inject memory reference into AGENTS.md**
+   - Compose the section between `<!-- MEMORY:START -->` and `<!-- MEMORY:END -->` markers:
+     ```
+     <!-- MEMORY:START -->
+     @MEMORY.md
+     <!-- MEMORY:END -->
+     ```
+   - The `@MEMORY.md` reference points to `.factory/memory/MEMORY.md` — Claude loads the full file directly, so no inline duplication is needed
+   - If AGENTS.md already has MEMORY markers, replace the section between them
+   - If AGENTS.md has no MEMORY markers, append the section at the end
+   - If no AGENTS.md exists, create one with just the memory section
+
+6. **Update processed manifest**
+   - Append paths of newly processed stashes to `.factory/memory/.processed`
+
+7. **Report to user**
+   - Number of stashes processed
+   - Facts count (total, new)
+   - Episodes count (total, new)
+   - Preferences count by confidence tier
+   - Confirm MEMORY.md and AGENTS.md updated
+
+**File locations (all project-local)**
+- Memory file: `.factory/memory/MEMORY.md` (single source of truth, referenced as @MEMORY.md)
+- Stash files: `.factory/stash/*.md`
+- Friction output: `.factory/friction/antigen_clusters.json` (clustered patterns with user contexts)
+- Friction fallback: `.factory/friction/antigen_review.md` (human-readable clusters)
+- Processed manifest: `.factory/memory/.processed`
+- Output: `AGENTS.md` (managed MEMORY section with @MEMORY.md reference)

package/packages/droid/droids/context-builder.md

@@ -1,7 +1,7 @@
 ---
 name: context-builder
 description: Initialize or update project context documentation
-when_to_use: Use to initialize Claude Code context for new/existing projects, discover and organize documentation, create CLAUDE.md and KNOWLEDGE_BASE.md for optimal token-efficient memory
+when_to_use: Use to initialize Droid context for new/existing projects, discover and organize documentation, create AGENTS.md and KNOWLEDGE_BASE.md for optimal token-efficient memory
 model: inherit
 tools: ["Read", "LS", "Grep", "Glob", "Create", "Edit", "MultiEdit", "ApplyPatch", "Execute", "WebSearch", "FetchUrl", "mcp"]
 ---
@@ -35,17 +35,17 @@ digraph ContextBuilder {
 
   // Scan phase
   scan [label="Scan existing docs\n& project type"];
-  exists [label="CLAUDE.md\nexists?", shape=diamond];
+  exists [label="AGENTS.md\nexists?", shape=diamond];
 
   // Update path
-  read_existing [label="Read existing\nCLAUDE.md"];
+  read_existing [label="Read existing\nAGENTS.md"];
   merge_update [label="Merge updates\npreserve structure"];
   update_tiers [label="Update Tier 2/3\nif needed"];
 
   // Create path
   create_t3 [label="Create Tier 3\ndocs/*.md"];
   create_t2 [label="Create Tier 2\nKNOWLEDGE_BASE.md"];
-  create_t1 [label="Create Tier 1\nCLAUDE.md"];
+  create_t1 [label="Create Tier 1\nAGENTS.md"];
 
   // Validation
   validate [label="Validate limits\n& anti-patterns"];
@@ -85,21 +85,23 @@ digraph ContextBuilder {
 
 | Tier | File | Lines | Tokens | Purpose |
 |------|------|-------|--------|---------|
-| 1 | CLAUDE.md | < 95 | < 2,000 | Daily essentials, always loaded |
+| 1 | AGENTS.md | < 95 | < 2,000 | Daily essentials, always loaded |
 | 2 | docs/KNOWLEDGE_BASE.md | < 100 | < 1,500 | TOC with 1-2 line summaries |
 | 3 | docs/*.md | Unlimited | Unlimited | Comprehensive details |
 
-**Flow:** CLAUDE.md → KNOWLEDGE_BASE.md → docs/*.md (progressive disclosure)
+**Flow:** AGENTS.md → KNOWLEDGE_BASE.md → docs/*.md (progressive disclosure)
 
 **Rule:** Plain text paths only (no @ triggers) in Tier 1 and 2
 
+**Permanent reference:** `@MEMORY.md` from `.factory/memory/MEMORY.md` — this is the only file allowed to use @ for direct loading. It contains project memory (facts, episodes, preferences) auto-generated by `/remember`. Always check for it during discovery. If it exists, include it as a source and ensure AGENTS.md references it.
+
 # Anti-Patterns
 
 | Don't | Why |
 |-------|-----|
 | @ triggers in markdown | Bloats context window |
 | Comprehensive content in KNOWLEDGE_BASE.md | It's a TOC, not a database |
-| Embedded agent/skill definitions | Don't duplicate ~/.claude/ |
+| Embedded droid/command definitions | Don't duplicate ~/.factory/ |
 | ASCII trees (├─ └─) | Use arrows (→) or tables |
 | "How to" boilerplate | Remove instructional text |
 
@@ -114,10 +116,10 @@ Create detailed docs: `architecture.md`, `development.md`, `api-reference.md`, `
 ## 3. Tier 2: KNOWLEDGE_BASE.md (TOC)
 Format: `## Topic` + 1-2 sentence summary + `→ docs/file.md`
 
-## 4. Tier 1: CLAUDE.md (Essentials)
+## 4. Tier 1: AGENTS.md (Essentials)
 Include: Project summary (2-3 sentences), Tech stack (list), Commands (essential only), Key patterns (top 3), Pointer to `docs/KNOWLEDGE_BASE.md`
 
-## 5. Update Existing (when CLAUDE.md exists)
+## 5. Update Existing (when AGENTS.md exists)
 Read existing → Preserve structure → Merge new info → Update Tier 2/3 if needed → Validate limits
 
 ## 6. Validation
@@ -125,18 +127,18 @@ Check limits (see 3-Tier table), no @ triggers, no ASCII trees.
 
 # Content Placement
 
-| Content | CLAUDE.md | KNOWLEDGE_BASE.md | docs/*.md |
+| Content | AGENTS.md | KNOWLEDGE_BASE.md | docs/*.md |
 |---------|-----------|-------------------|-----------|
-| Project summary | 2-3 sentences | ❌ | ❌ |
+| Project summary | 2-3 sentences | - | - |
 | Tech stack | List only | 1-line summary | Full details |
 | Commands | Essential only | ❌ | All commands |
 | Architecture | ❌ | 1-2 line summary | Full design |
 | API/Troubleshooting | ❌ | 1-2 line summary | Full content |
 
-**Rule:** If used every session → CLAUDE.md. If need to know it exists → KNOWLEDGE_BASE.md. If need details → docs/*.md
+**Rule:** If used every session → AGENTS.md. If need to know it exists → KNOWLEDGE_BASE.md. If need details → docs/*.md
 
 # Emergency Compression
 
 If over limits: Remove non-essentials, compress to 1 sentence, use tables, combine topics. For docs/*.md >500 lines: split by topic.
 
-You create lightweight indexes (Tier 1-2) that point to comprehensive docs (Tier 3). Never bloat CLAUDE.md or KNOWLEDGE_BASE.md.
+You create lightweight indexes (Tier 1-2) that point to comprehensive docs (Tier 3). Never bloat AGENTS.md or KNOWLEDGE_BASE.md.

package/packages/opencode/AGENTS.md

@@ -22,7 +22,7 @@ These subagents are available when using Claude Code CLI. Opencode can reference
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-## Opencode Commands (20 total)
+## Opencode Commands (22 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
@@ -32,9 +32,11 @@ These subagents are available when using Claude Code CLI. Opencode can reference
 | debug | Debug an issue systematically using structured investigation techniques | /debug <issue-description> | - |
 | docs-builder | Create comprehensive project documentation with structured /docs hierarchy | /docs-builder | false |
 | explain | Explain code for someone new to the codebase | /explain <code-section> | - |
+| friction | Analyze session logs for failure patterns and behavioral signals | /friction <sessions-path> | - |
 | git-commit | Analyze changes and create intelligent git commits | /git-commit | - |
 | optimize | Analyze and optimize performance issues | /optimize <target-area> | - |
 | refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> | - |
+| remember | Consolidate stashes + friction into project memory | /remember | - |
 | review | Comprehensive code review including quality, tests, and architecture | /review | - |
 | root-cause-tracing | Systematically traces bugs backward through call stack to identify source | /root-cause-tracing <issue-description> | false |
 | security | Security vulnerability scan and analysis | /security | - |

package/packages/opencode/agent/context-builder.md

@@ -1,7 +1,7 @@
 ---
 name: context-builder
 description: Initialize or update project context documentation
-when_to_use: Use to initialize Claude Code context for new/existing projects, discover and organize documentation, create CLAUDE.md and KNOWLEDGE_BASE.md for optimal token-efficient memory
+when_to_use: Use to initialize OpenCode context for new/existing projects, discover and organize documentation, create AGENTS.md and KNOWLEDGE_BASE.md for optimal token-efficient memory
 mode: subagent
 temperature: 0.2
 tools:
@@ -39,17 +39,17 @@ digraph ContextBuilder {
 
   // Scan phase
   scan [label="Scan existing docs\n& project type"];
-  exists [label="CLAUDE.md\nexists?", shape=diamond];
+  exists [label="AGENTS.md\nexists?", shape=diamond];
 
   // Update path
-  read_existing [label="Read existing\nCLAUDE.md"];
+  read_existing [label="Read existing\nAGENTS.md"];
   merge_update [label="Merge updates\npreserve structure"];
   update_tiers [label="Update Tier 2/3\nif needed"];
 
   // Create path
   create_t3 [label="Create Tier 3\ndocs/*.md"];
   create_t2 [label="Create Tier 2\nKNOWLEDGE_BASE.md"];
-  create_t1 [label="Create Tier 1\nCLAUDE.md"];
+  create_t1 [label="Create Tier 1\nAGENTS.md"];
 
   // Validation
   validate [label="Validate limits\n& anti-patterns"];
@@ -89,21 +89,23 @@ digraph ContextBuilder {
 
 | Tier | File | Lines | Tokens | Purpose |
 |------|------|-------|--------|---------|
-| 1 | CLAUDE.md | < 95 | < 2,000 | Daily essentials, always loaded |
+| 1 | AGENTS.md | < 95 | < 2,000 | Daily essentials, always loaded |
 | 2 | docs/KNOWLEDGE_BASE.md | < 100 | < 1,500 | TOC with 1-2 line summaries |
 | 3 | docs/*.md | Unlimited | Unlimited | Comprehensive details |
 
-**Flow:** CLAUDE.md → KNOWLEDGE_BASE.md → docs/*.md (progressive disclosure)
+**Flow:** AGENTS.md → KNOWLEDGE_BASE.md → docs/*.md (progressive disclosure)
 
 **Rule:** Plain text paths only (no @ triggers) in Tier 1 and 2
 
+**Permanent reference:** `@MEMORY.md` from `.opencode/memory/MEMORY.md` — this is the only file allowed to use @ for direct loading. It contains project memory (facts, episodes, preferences) auto-generated by `/remember`. Always check for it during discovery. If it exists, include it as a source and ensure AGENTS.md references it.
+
 # Anti-Patterns
 
 | Don't | Why |
 |-------|-----|
 | @ triggers in markdown | Bloats context window |
 | Comprehensive content in KNOWLEDGE_BASE.md | It's a TOC, not a database |
-| Embedded agent/skill definitions | Don't duplicate ~/.claude/ |
+| Embedded agent/command definitions | Don't duplicate ~/.config/opencode/ |
 | ASCII trees (├─ └─) | Use arrows (→) or tables |
 | "How to" boilerplate | Remove instructional text |
 
@@ -118,10 +120,10 @@ Create detailed docs: `architecture.md`, `development.md`, `api-reference.md`, `
 ## 3. Tier 2: KNOWLEDGE_BASE.md (TOC)
 Format: `## Topic` + 1-2 sentence summary + `→ docs/file.md`
 
-## 4. Tier 1: CLAUDE.md (Essentials)
+## 4. Tier 1: AGENTS.md (Essentials)
 Include: Project summary (2-3 sentences), Tech stack (list), Commands (essential only), Key patterns (top 3), Pointer to `docs/KNOWLEDGE_BASE.md`
 
-## 5. Update Existing (when CLAUDE.md exists)
+## 5. Update Existing (when AGENTS.md exists)
 Read existing → Preserve structure → Merge new info → Update Tier 2/3 if needed → Validate limits
 
 ## 6. Validation
@@ -129,7 +131,7 @@ Check limits (see 3-Tier table), no @ triggers, no ASCII trees.
 
 # Content Placement
 
-| Content | CLAUDE.md | KNOWLEDGE_BASE.md | docs/*.md |
+| Content | AGENTS.md | KNOWLEDGE_BASE.md | docs/*.md |
 |---------|-----------|-------------------|-----------|
 | Project summary | 2-3 sentences | ❌ | ❌ |
 | Tech stack | List only | 1-line summary | Full details |
@@ -137,10 +139,10 @@ Check limits (see 3-Tier table), no @ triggers, no ASCII trees.
 | Architecture | ❌ | 1-2 line summary | Full design |
 | API/Troubleshooting | ❌ | 1-2 line summary | Full content |
 
-**Rule:** If used every session → CLAUDE.md. If need to know it exists → KNOWLEDGE_BASE.md. If need details → docs/*.md
+**Rule:** If used every session → AGENTS.md. If need to know it exists → KNOWLEDGE_BASE.md. If need details → docs/*.md
 
 # Emergency Compression
 
 If over limits: Remove non-essentials, compress to 1 sentence, use tables, combine topics. For docs/*.md >500 lines: split by topic.
 
-You create lightweight indexes (Tier 1-2) that point to comprehensive docs (Tier 3). Never bloat CLAUDE.md or KNOWLEDGE_BASE.md.
+You create lightweight indexes (Tier 1-2) that point to comprehensive docs (Tier 3). Never bloat AGENTS.md or KNOWLEDGE_BASE.md.

package/packages/opencode/command/docs-builder/templates.md

@@ -2,6 +2,35 @@
 
 Detailed templates for each file in the /docs structure.
 
+## 00-context/blueprint.md
+
+```markdown
+# [Project Name] Blueprint
+
+## Identity
+[What this project IS in 2-3 sentences. Sourced from README.]
+
+## Status
+| Area | Status | Notes |
+|------|--------|-------|
+| [feature/module] | implemented / in-progress / planned | [brief] |
+
+## Architecture
+[High-level structure: packages, modules, entry points. Tables or flat lists, no ASCII trees.]
+
+## Implemented
+[What works today. Group by feature area. Be specific about what ships.]
+
+## Planned
+[What's next. Ordered by priority. Link to design docs if they exist.]
+
+## Future Direction
+[Where does this project want to be? North star. 3-5 bullets max.]
+
+## Key Decisions
+[Major architectural choices already made. Brief rationale. Link to decisions-log if available.]
+```
+
 ## 00-context/vision.md
 
 ```markdown