Hugo Nijhuis
cdfacbac18
- Move legacy content to legacy/ folder (old, old2, docs, learnings, scripts) - Create new .opencode/ structure with skills/, tools/, agents/ folders - Update Makefile to symlink to ~/.config/opencode/ instead of ~/.claude/ - Update Makefile to manage skills, tools, and agents (remove settings.json) - Simplify install/uninstall (no backup logic) - Add README.md documenting the new structure - Keep settings.json as historical reference
Learnings
This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:
- Historical record: What we learned and when
- Governance reference: Why we work the way we do
- Encoding source: Input that gets encoded into skills and agents
The Learning Flow
Experience → Learning captured → Encoded into system → Knowledge is actionable
↓
Stays here for:
- Historical reference
- Governance validation
- Periodic review
Learnings are not the final destination. They are inputs that get encoded into skills and agents where Claude can actually use them. But we keep the learning file as a record of why we encoded what we did.
Writing a Learning
Create a new file: YYYY-MM-DD-short-title.md
Use this template:
# [Title]
**Date**: YYYY-MM-DD
**Context**: What triggered this learning (task, incident, observation)
## Learning
The insight we gained. Be specific and actionable.
## Encoded In
Where this learning has been (or will be) encoded:
- `skills/xxx/SKILL.md` - What was added/changed
- `agents/xxx/AGENT.md` - What was added/changed
If not yet encoded, note: "Pending: Issue #XX"
## Governance
What this learning means for how we work going forward. This is the "why" that justifies the encoding.
Encoding Process
- Capture the learning in this folder
- Create an issue to encode it into the appropriate location
- Update the skill/agent with the encoded knowledge
- Update the learning file with the "Encoded In" references
The goal: Claude should be able to use the learning, not just read about it.
What Gets Encoded Where
| Learning Type | Encode In |
|---|---|
| How to use a tool | skills/ (background skill) |
| Workflow improvement | skills/ (user-invocable skill) |
| Subtask behavior | agents/ |
| Organization belief | manifesto.md |
| Product direction | vision.md (in product repo) |
Periodic Review
Periodically review learnings to:
- Verify encoded locations still reflect the learning
- Check if governance is still being followed
- Identify patterns across multiple learnings
- Archive or update outdated learnings
Naming Convention
Files follow the pattern: YYYY-MM-DD-short-kebab-title.md
Examples:
2024-01-15-always-use-comments-flag.md2024-01-20-verify-before-cleanup.md2024-02-01-small-prs-merge-faster.md