docs: expand scope and add comprehensive documentation

Create README.md and enhance AGENTS.md to position this as an extensible framework for any Opencode skills and agents, not just PARA/task management. Includes installation, development workflow, code style guidelines, and Nix flake integration patterns.
2026-01-06 05:52:07 +01:00
commit ac0da8c1cd
32 changed files with 4415 additions and 0 deletions
--- a/skill/reflection/SKILL.md
+++ b/skill/reflection/SKILL.md
@@ -0,0 +1,262 @@
+---
+name: reflection
+description: "Conversation analysis to improve skills based on user feedback. Use when: (1) user explicitly requests reflection ('reflect', 'improve', 'learn from this'), (2) reflection mode is ON and clear correction signals detected, (3) user asks to analyze skill performance. Triggers: reflect, improve, learn, analyze conversation, skill feedback. Toggle with /reflection on|off command."
+compatibility: opencode
+---
+
+# Reflection
+
+Analyze conversations to detect user corrections, preferences, and observations, then propose skill improvements.
+
+## Reflection Mode
+
+**Toggle:** Use `/reflection on|off|status` command
+
+**When mode is ON:**
+- Actively monitor for correction signals during conversation
+- Auto-suggest reflection when clear patterns detected
+- Proactively offer skill improvements
+
+**When mode is OFF (default):**
+- Only trigger on explicit user request
+- No automatic signal detection
+
+## Core Workflow
+
+When triggered, follow this sequence:
+
+### 1. Identify Target Skill
+
+**If skill explicitly mentioned:**
+```
+User: "Reflect on the task-management skill"
+→ Target: task-management
+```
+
+**If not specified, ask:**
+```
+"Which skill should I analyze? Recent skills used: [list from session]"
+```
+
+### 2. Scan Conversation
+
+Use session tools to analyze the current conversation:
+
+```bash
+# Read current session messages
+session_read --session_id [current] --include_todos true
+```
+
+**Analyze for:**
+- When target skill was used
+- User responses after skill usage
+- Correction signals (see references/signal-patterns.md)
+- Workflow patterns
+- Repeated interactions
+
+### 3. Classify Findings
+
+Rate each finding using 3-tier system (see references/rating-guidelines.md):
+
+**HIGH (Explicit Constraints):**
+- Direct corrections: "No, don't do X"
+- Explicit rules: "Always/Never..."
+- Repeated violations
+
+**MEDIUM (Preferences & Patterns):**
+- Positive reinforcement: "That's perfect"
+- Adopted patterns (used 3+ times)
+- Workflow optimizations
+
+**LOW (Observations):**
+- Contextual insights
+- Tentative patterns
+- Environmental preferences
+
+### 4. Read Target Skill
+
+Before proposing changes, read the current skill implementation:
+
+```bash
+# Read the skill file
+read skill/[target-skill]/SKILL.md
+
+# Check for references if needed
+glob pattern="**/*.md" path=skill/[target-skill]/references/
+```
+
+### 5. Generate Proposals
+
+**For each finding, create:**
+
+**HIGH findings:**
+- Specific constraint text to add
+- Location in skill where it should go
+- Exact wording for the rule
+
+**MEDIUM findings:**
+- Preferred approach description
+- Suggested default behavior
+- Optional: code example or workflow update
+
+**LOW findings:**
+- Observation description
+- Potential future action
+- Context for when it might apply
+
+### 6. User Confirmation
+
+**Present findings in structured format:**
+
+```markdown
+## Reflection Analysis: [Skill Name]
+
+### HIGH Priority (Constraints)
+1. **[Finding Title]**
+   - Signal: [What user said/did]
+   - Proposed: [Specific change to skill]
+
+### MEDIUM Priority (Preferences)
+1. **[Finding Title]**
+   - Signal: [What user said/did]
+   - Proposed: [Suggested update]
+
+### LOW Priority (Observations)
+[List observations]
+
+---
+
+Approve changes to [skill name]? (yes/no/selective)
+```
+
+### 7. Apply Changes or Document
+
+**If user approves (yes):**
+1. Edit skill/[target-skill]/SKILL.md with proposed changes
+2. Confirm: "Updated [skill name] with [N] improvements"
+3. Show diff of changes
+
+**If user selects some (selective):**
+1. Ask which findings to apply
+2. Edit skill with approved changes only
+3. Write rejected findings to OBSERVATIONS.md
+
+**If user declines (no):**
+1. Create/append to skill/[target-skill]/OBSERVATIONS.md
+2. Document all findings with full context
+3. Confirm: "Documented [N] observations in OBSERVATIONS.md for future reference"
+
+## OBSERVATIONS.md Format
+
+When writing observations file:
+
+```markdown
+# Observations for [Skill Name]
+
+Generated: [Date]
+From conversation: [Session ID if available]
+
+## HIGH: [Finding Title]
+**Context:** [Which scenario/workflow]
+**Signal:** [User's exact words or repeated pattern]
+**Constraint:** [The rule to follow]
+**Proposed Change:** [Exact text to add to skill]
+**Status:** Pending user approval
+
+---
+
+## MEDIUM: [Finding Title]
+**Context:** [Which scenario/workflow]
+**Signal:** [What indicated this preference]
+**Preference:** [The preferred approach]
+**Rationale:** [Why this works well]
+**Proposed Change:** [Suggested skill update]
+**Status:** Pending user approval
+
+---
+
+## LOW: [Observation Title]
+**Context:** [Which scenario/workflow]
+**Signal:** [What was noticed]
+**Observation:** [The pattern or insight]
+**Potential Action:** [Possible future improvement]
+**Status:** Noted for future consideration
+```
+
+## Signal Detection Patterns
+
+Key patterns to watch for (detailed in references/signal-patterns.md):
+
+**Explicit corrections:**
+- "No, that's wrong..."
+- "Actually, you should..."
+- "Don't do X, do Y instead"
+
+**Repeated clarifications:**
+- User explains same thing multiple times
+- Same mistake corrected across sessions
+
+**Positive patterns:**
+- "Perfect, keep doing it this way"
+- User requests same approach repeatedly
+- "That's exactly what I needed"
+
+**Workflow corrections:**
+- "You skipped step X"
+- "Wrong order"
+- "You should have done Y first"
+
+## Usage Examples
+
+### Example 1: Post-Skill Usage
+
+```
+User: "Reflect on how the task-management skill performed"
+
+Agent:
+1. Read current session
+2. Find all task-management skill invocations
+3. Analyze user responses afterward
+4. Read skill/task-management/SKILL.md
+5. Present findings with confirmation prompt
+```
+
+### Example 2: User-Prompted Learning
+
+```
+User: "Learn from this conversation - I had to correct you several times"
+
+Agent:
+1. Ask which skill to analyze (if multiple used)
+2. Scan full conversation for correction signals
+3. Classify by severity (HIGH/MEDIUM/LOW)
+4. Propose changes with confirmation
+```
+
+### Example 3: Detected Signals
+
+```
+# During conversation, user corrects workflow twice
+User: "No, run tests BEFORE committing, not after"
+[later]
+User: "Again, tests first, then commit"
+
+# Later when user says "reflect" or at end of session
+Agent detects: HIGH priority constraint for relevant skill
+```
+
+## References
+
+- **signal-patterns.md** - Comprehensive list of correction patterns to detect
+- **rating-guidelines.md** - Decision tree for classifying findings (HIGH/MEDIUM/LOW)
+
+Load these when analyzing conversations for detailed pattern matching and classification logic.
+
+## Important Constraints
+
+1. **Never edit skills without user approval** - Always confirm first
+2. **Read the skill before proposing changes** - Avoid suggesting what already exists
+3. **Preserve existing structure** - Match the skill's current organization and style
+4. **Be specific** - Vague observations aren't actionable
+5. **Full conversation scan** - Don't just analyze last few messages
+6. **Context matters** - Include why the finding matters, not just what was said
--- a/skill/reflection/references/command-usage.md
+++ b/skill/reflection/references/command-usage.md
@@ -0,0 +1,85 @@
+# Reflection Command Usage
+
+## Toggle Commands
+
+### Enable Reflection Mode
+```
+/reflection on
+```
+
+**Effect:** Enables automatic detection of correction signals during conversation. I will proactively suggest skill improvements when patterns are detected.
+
+### Disable Reflection Mode  
+```
+/reflection off
+```
+
+**Effect:** Disables automatic detection. Reflection only occurs when explicitly requested.
+
+### Check Status
+```
+/reflection status
+```
+
+**Effect:** Shows whether reflection mode is currently on or off.
+
+## Behavior by Mode
+
+### Mode: ON
+
+**Automatic triggers:**
+- User corrects same thing 2+ times → Offer reflection
+- Explicit corrections detected ("No, do it this way") → Ask "Should I reflect on [skill]?"
+- After skill usage with clear signals → Proactive suggestion
+
+**Example:**
+```
+User: "No, run tests before committing, not after"
+[conversation continues]
+User: "Again, tests must run first"
+
+Agent: "I notice you've corrected the workflow order twice. 
+Should I reflect on the relevant skill to add this constraint?"
+```
+
+### Mode: OFF (Default)
+
+**Manual triggers only:**
+- User says "reflect", "improve", "learn from this"
+- User explicitly asks to analyze skill
+
+**Example:**
+```
+User: "Reflect on the task-management skill"
+
+Agent: [Runs full reflection workflow]
+```
+
+## Session Persistence
+
+Reflection mode is **session-scoped**:
+- Setting persists for current conversation
+- Resets to OFF for new sessions
+- Use `/reflection on` at session start if desired
+
+## When to Use Each Mode
+
+### Use ON when:
+- Actively developing/tuning a new skill
+- Testing skill behavior with real usage
+- Learning preferences for a new domain
+- Want proactive improvement suggestions
+
+### Use OFF when:
+- Skills are stable and working well
+- Don't want interruptions
+- Only need reflection occasionally
+- Prefer manual control
+
+## Integration with Skill
+
+The reflection skill checks conversation context for mode state:
+- Looks for recent `/reflection on` or `/reflection off` commands
+- Defaults to OFF if no command found
+- Auto-triggers only when ON and signals detected
+- Always responds to explicit "reflect" requests regardless of mode
--- a/skill/reflection/references/rating-guidelines.md
+++ b/skill/reflection/references/rating-guidelines.md
@@ -0,0 +1,126 @@
+# Rating Guidelines
+
+How to classify findings from conversation analysis.
+
+## Rating Criteria
+
+### High Priority (Explicit Constraints)
+
+**Definition:** Direct corrections or explicit rules that MUST be followed.
+
+**Characteristics:**
+- User explicitly states a constraint
+- Correction of incorrect behavior
+- Safety or correctness requirements
+- Repeated violations cause frustration
+
+**Examples:**
+- "Never commit without asking first"
+- "Always use TypeScript, not JavaScript"
+- "You forgot to run tests before committing"
+- "Don't use global state"
+
+**Action:** These become hard constraints in the skill documentation.
+
+**Format in OBSERVATIONS.md:**
+```markdown
+## HIGH: [Constraint Title]
+**Context:** [Which skill/scenario]
+**Signal:** [What the user said/did]
+**Constraint:** [The specific rule to follow]
+**Proposed Change:** [Exact text to add to skill]
+```
+
+### Medium Priority (Preferences & Patterns)
+
+**Definition:** Approaches that work well or user preferences that improve workflow.
+
+**Characteristics:**
+- Positive reinforcement from user
+- Patterns that user adopts repeatedly
+- Workflow optimizations
+- Style preferences
+
+**Examples:**
+- "That output format is perfect, use that"
+- User consistently requests bullet points over paragraphs
+- User prefers parallel tool execution
+- "I like how you broke that down"
+
+**Action:** These become preferred approaches or default patterns in skills.
+
+**Format in OBSERVATIONS.md:**
+```markdown
+## MEDIUM: [Preference Title]
+**Context:** [Which skill/scenario]
+**Signal:** [What the user said/did]
+**Preference:** [The preferred approach]
+**Rationale:** [Why this works well]
+**Proposed Change:** [Suggested skill update]
+```
+
+### Low Priority (Observations)
+
+**Definition:** Contextual insights, minor preferences, or exploratory findings.
+
+**Characteristics:**
+- Environmental context
+- Tentative patterns (need more data)
+- Nice-to-have improvements
+- Exploratory feedback
+
+**Examples:**
+- User tends to work on deep tasks in morning
+- User sometimes asks for alternative approaches
+- User occasionally needs extra context
+- Formatting preferences for specific outputs
+
+**Action:** Document for future consideration. May become higher priority with more evidence.
+
+**Format in OBSERVATIONS.md:**
+```markdown
+## LOW: [Observation Title]
+**Context:** [Which skill/scenario]
+**Signal:** [What was noticed]
+**Observation:** [The pattern or insight]
+**Potential Action:** [Possible future improvement]
+```
+
+## Classification Decision Tree
+
+```
+1. Did user explicitly correct behavior?
+   YES → HIGH
+   NO → Continue
+
+2. Did user express satisfaction with approach?
+   YES → Was it repeated/adopted as pattern?
+      YES → MEDIUM
+      NO → LOW
+   NO → Continue
+
+3. Is this a repeated pattern (3+ instances)?
+   YES → MEDIUM
+   NO → LOW
+
+4. Is this exploratory/tentative?
+   YES → LOW
+```
+
+## Edge Cases
+
+**Implicit corrections (repeated fixes by user):**
+- First instance: LOW (observe)
+- Second instance: MEDIUM (pattern emerging)
+- Third instance: HIGH (clear constraint)
+
+**Contradictory signals:**
+- Document both
+- Note the contradiction
+- Mark for user clarification
+
+**Context-dependent preferences:**
+- Rate based on specificity
+- Document the context clearly
+- If context is always present: MEDIUM
+- If context is occasional: LOW
--- a/skill/reflection/references/signal-patterns.md
+++ b/skill/reflection/references/signal-patterns.md
@@ -0,0 +1,79 @@
+# User Correction Signal Patterns
+
+Patterns that indicate the user is correcting or refining the agent's behavior.
+
+## High Priority Signals (Explicit Corrections)
+
+**Direct corrections:**
+- "No, that's not right..."
+- "Actually, you should..."
+- "Don't do X, instead do Y"
+- "That's incorrect..."
+- "You misunderstood..."
+
+**Explicit instructions:**
+- "Always..." / "Never..."
+- "From now on..."
+- "Make sure to..."
+- "Remember to..."
+
+**Repeated clarifications:**
+- User re-explains the same point multiple times
+- User provides same instruction in different words
+- User corrects same mistake in multiple sessions
+
+**Workflow corrections:**
+- "You skipped step X"
+- "You should have done Y first"
+- "That's the wrong order"
+
+## Medium Priority Signals (Effective Patterns)
+
+**Positive reinforcement:**
+- "That's perfect"
+- "Exactly what I needed"
+- "Great, keep doing it this way"
+- "Yes, that's the right approach"
+
+**User adopts the pattern:**
+- User requests same workflow multiple times
+- User references previous successful interaction
+- User asks to "do it like last time"
+
+**Implicit preferences:**
+- User consistently asks for specific format
+- User regularly requests certain tools/approaches
+- Patterns in how user phrases requests
+
+## Low Priority Signals (Observations)
+
+**General feedback:**
+- "Hmm, interesting..."
+- "I see..."
+- Neutral acknowledgments
+
+**Exploratory questions:**
+- "What if we tried..."
+- "Could you also..."
+- "I wonder if..."
+
+**Context clues:**
+- Time of day patterns
+- Task batching preferences
+- Communication style preferences
+
+**Environment signals:**
+- Tools user prefers
+- File organization patterns
+- Workflow preferences
+
+## Anti-Patterns (Not Corrections)
+
+**Questions about capabilities:**
+- "Can you do X?" (not a correction, just inquiry)
+
+**Exploration:**
+- "Let's try something different" (exploration, not correction)
+
+**Context changes:**
+- "Now let's work on Y" (topic shift, not correction)