enso-reference - SKILL.md Agent Skill

name: enso-reference description: Show the enso system overview, skill directory, workflow, and live project status. Use when an agent or user needs a quick orientation to the current enso project's state, commands, and conventions. license: MIT compatibility: opencode

When to Use

Load this skill when:

You need a quick reference for enso conventions or directory structure
A user asks "what is enso?" or "how does this project work?"
You are orienting yourself in an active enso project mid-session
You want to see the current project status: active stories, log count, lessons

This is a read-only skill. No files are modified.

Reference

ENSO — Seam-Oriented Harness Protocol

A minimal system for managing AI agent context across sessions. Treats context as a scarce resource — load only what's needed, persist before it's lost, compact before overflow.

Key Skills

Skill	Purpose
`session-start`	Start session. Loads PRD, ARCHITECTURE, LESSONS, recent logs, and detects the active story. Bootstraps new projects on first use.
`session-persist`	Close/pause session. Drafts a session log, lessons, and story updates for your review. Writes nothing until confirmed.
`read-session-logs`	Show last N session logs (default: 5). Read-only.
`enso-reference`	Show this reference.

The Six Operations

Operation	What It Does
Write	Persist information outside the context window
Select	Load only what's needed right now
Probe	Actively search (grep, LSP, glob) for answers
Compress	Summarize to fit the token budget
Isolate	Split work across scopes
Assign	Match task to the right agent

Directory Structure

docs/
  core/                  # Source of truth
    PRD.md               # Problem, goals, scope
    ARCHITECTURE.md      # System overview, key decisions
    QUEUE.md             # Optional: prioritized story scheduler
  stories/               # Active work items (one file per story)
  reference/             # Long-term memory
    LESSONS.md           # Accumulated patterns and gotchas
    completed/           # Finished stories
  skills/                # Reusable procedures and scripts
  logs/                  # Session history (auto-generated by session-persist)

Typical Session Workflow

1. session-start      → load context, confirm active story (bootstraps if new project)
2. ... do work ...
3. session-persist    → capture lessons, write session log (or pause)

Best Practices

Start and close every session with session-start and session-persist.
Compact proactively — don't wait for overflow; summarize at ~80% context.
Keep stories tightly scoped — one goal, explicit write/read/exclude boundaries.
Plan before executing — complete the story's Approach section before touching files.
Capture lessons immediately — session-persist is the moment to record insights.
Build tools, don't just use them — when you hit friction, author a skill. Software builds software.
Update, don't accumulate — edit docs in place; git preserves history.

Project Status (Dynamic)

Run these commands to show live status:

Active stories:

count=$(ls docs/stories/*.md 2>/dev/null | wc -l)
echo "  Active: $count"
ls docs/stories/*.md 2>/dev/null | while read f; do
  title=$(head -1 "$f" | sed 's/^# //')
  echo "  - $title"
done || echo "  No active stories found"

Session logs:

count=$(ls docs/logs/*.md 2>/dev/null | wc -l)
echo "  Total: $count"
latest=$(ls -t docs/logs/*.md 2>/dev/null | head -1)
[ -n "$latest" ] && echo "  Last: $(basename $latest)" || echo "  No logs yet"

Lessons:

[ -f docs/reference/LESSONS.md ] && echo "  LESSONS.md: $(wc -l < docs/reference/LESSONS.md) lines" || echo "  No LESSONS.md yet"

Completed stories:

count=$(ls docs/reference/completed/*.md 2>/dev/null | wc -l 2>/dev/null) && echo "  Completed: $count" || echo "  Completed: 0"