Compare commits
5 Commits
2defcf3550
..
master
| Author | SHA1 | Date | |
|---|---|---|---|
 sampson
|
9ea53542df | ||
|
sampson
|
92b7408c7e | ||
|
sampson
|
15711cea45 | ||
|
sampson
|
302d43a262 | ||
|
sampson
|
a08ee3d5c8 |
@@ -0,0 +1,70 @@
|
||||
# opencode-skills
|
||||
|
||||
Reusable skills and commands for AI coding agents (OpenCode and Claude Code).
|
||||
|
||||
Skills follow the [Agent Skills](https://agentskills.io) open standard, so each `SKILL.md` works across both platforms.
|
||||
|
||||
## Contents
|
||||
|
||||
- `skills/<name>/SKILL.md` — agent skills, discovered on demand.
|
||||
- `commands/*.md` — slash commands.
|
||||
|
||||
## Featured skill: `setup-context-system`
|
||||
|
||||
Guides a person through building a **layered context system** for their agent — global/project/initiative context files, index files, knowledge management (Rules/Hypotheses), decision logging, tone rules, an optional discovery methodology, and a maintenance command that keeps it all current. It teaches the pattern and interviews the user for their own content; the result is their system, not a copy.
|
||||
|
||||
It runs in phases (essentials first), gating after each so a user can stop with a working system at any point. Its final phase optionally offers to install [Superpowers](https://github.com/obra/superpowers) — obra's skills library that adds an automatic spec → plan → TDD workflow — as a process companion to this context layer.
|
||||
|
||||
## Installing a skill
|
||||
|
||||
A skill is a self-contained `SKILL.md`. Both platforms read skills from specific config directories — putting the file in those directories (or symlinking it there) is all that's required.
|
||||
|
||||
### Method 1 — Git clone + symlink (recommended, no drift)
|
||||
|
||||
Clone once, then symlink the skill into your agent's skills directory. Edits in the repo propagate automatically.
|
||||
|
||||
```bash
|
||||
git clone https://git.aileverte.be/sampson/opencode-skills.git
|
||||
cd opencode-skills
|
||||
|
||||
# OpenCode (global)
|
||||
ln -s "$PWD/skills/setup-context-system" ~/.config/opencode/skills/setup-context-system
|
||||
|
||||
# Claude Code (global)
|
||||
ln -s "$PWD/skills/setup-context-system" ~/.claude/skills/setup-context-system
|
||||
```
|
||||
|
||||
Then run it: type `/setup-context-system`, or just describe the task and let the agent invoke it.
|
||||
|
||||
> Paths are verified against the official docs:
|
||||
> - OpenCode reads `~/.config/opencode/skills/<name>/SKILL.md` (https://opencode.ai/docs/skills).
|
||||
> - Claude Code reads `~/.claude/skills/<name>/SKILL.md` (https://docs.claude.com/en/docs/claude-code/skills).
|
||||
|
||||
### Method 2 — Agent install from the raw file (no clone)
|
||||
|
||||
If you don't want to clone, have your agent fetch the raw `SKILL.md` and drop it into your skills directory. Tell the agent:
|
||||
|
||||
> Fetch `https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md`, save it to `~/.claude/skills/setup-context-system/SKILL.md` (or `~/.config/opencode/skills/setup-context-system/SKILL.md`), then run the `setup-context-system` skill.
|
||||
|
||||
Or do it manually:
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
mkdir -p ~/.claude/skills/setup-context-system
|
||||
curl -fsSL "https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md" \
|
||||
-o ~/.claude/skills/setup-context-system/SKILL.md
|
||||
|
||||
# OpenCode
|
||||
mkdir -p ~/.config/opencode/skills/setup-context-system
|
||||
curl -fsSL "https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md" \
|
||||
-o ~/.config/opencode/skills/setup-context-system/SKILL.md
|
||||
```
|
||||
|
||||
> Method 2 copies the file, so it won't pick up repo updates automatically. Method 1 (symlink) avoids drift.
|
||||
|
||||
## Project-scoped install
|
||||
|
||||
To make a skill available only inside one project instead of globally, place it under that project's config dir instead:
|
||||
|
||||
- OpenCode: `.opencode/skills/<name>/SKILL.md`
|
||||
- Claude Code: `.claude/skills/<name>/SKILL.md`
|
||||
@@ -0,0 +1,61 @@
|
||||
# /agenda
|
||||
|
||||
Produce a prioritized overview of all open tasks with agent-assist inference.
|
||||
|
||||
## Behavior
|
||||
|
||||
1. **Read all task files** in `todo/`, `ongoing/`, and `blocked/` folders at `~/Workspace/Personal/Tasks/`
|
||||
2. **Read all recurring definitions** in `meta/recurring/`
|
||||
3. **Sort tasks:**
|
||||
- Priority: High > Medium > Low
|
||||
- Within same priority: overdue first, then soonest due date, then TBD last
|
||||
4. **Infer agent-assistability** for each task based on description and context:
|
||||
- `Yes` -- task involves research, writing, analysis, code, document creation, data gathering
|
||||
- `Partial` -- task has agent-doable components mixed with human-only parts (meetings, decisions, calls)
|
||||
- `No` -- purely human tasks (meetings, calls, approvals, external dependencies with no prep work)
|
||||
5. **Output the agenda** in the format below
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## High Priority
|
||||
|
||||
| Task | Initiative | Due | Effort | Agent |
|
||||
|------|-----------|-----|--------|-------|
|
||||
| [task title] | [initiative] | [due or OVERDUE] | [effort] | [Yes/Partial/No] |
|
||||
|
||||
## Other Open Tasks
|
||||
|
||||
| Task | Initiative | Due | Priority | Effort | Agent |
|
||||
|------|-----------|-----|----------|--------|-------|
|
||||
| [task title] | [initiative] | [due] | [priority] | [effort] | [Yes/Partial/No] |
|
||||
|
||||
## Blocked
|
||||
|
||||
| Task | Initiative | Blocker | Agent |
|
||||
|------|-----------|---------|-------|
|
||||
| [task title] | [initiative] | [blocker summary from Notes] | [Yes/Partial/No] |
|
||||
|
||||
## Recurring
|
||||
|
||||
| Task | Frequency | Next | Agent |
|
||||
|------|-----------|------|-------|
|
||||
| [task title] | [frequency] | [next occurrence] | [Yes/Partial/No] |
|
||||
|
||||
## Summary
|
||||
|
||||
- X open tasks (Y high priority, Z overdue)
|
||||
- A in progress, B blocked
|
||||
- N tasks where agent can assist
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **High Priority table** includes all tasks with Priority: High from `todo/` and `ongoing/`
|
||||
- **Other Open Tasks table** includes Medium and Low priority tasks from `todo/` and `ongoing/`
|
||||
- **Blocked table** shows all tasks in `blocked/` regardless of priority
|
||||
- Tasks in `ongoing/` show their folder status as context (mention "in progress" in the row or table header)
|
||||
- **Overdue detection:** if Due date is before today's date, mark as OVERDUE in the Due column
|
||||
- Do NOT read `done/` or `cancelled/` folders
|
||||
- Keep output concise -- no descriptions, just the table fields
|
||||
- If a task's due date is relative (e.g., "Before integration testing"), display it as-is
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
description: Extract learnings, domain knowledge, and decisions from the session and propose updates to context files
|
||||
---
|
||||
|
||||
Review the current conversation and summarize everything learned about Sam's preferences, workflows, decisions, domain knowledge, and way of working that is NOT already captured in the existing context files.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Read the relevant context files to understand what is already documented:
|
||||
- ~/.config/opencode/AGENTS.md (global preferences)
|
||||
- The current project's AGENTS.md (if one exists)
|
||||
- ~/LLM Context/AGENTS.md (context system and file organization)
|
||||
- Any initiative-specific AGENTS.md files that were referenced in this session
|
||||
- Any other context files that were loaded during this session
|
||||
- ~/.config/opencode/skills/*/SKILL.md (existing skill definitions)
|
||||
- ~/.config/opencode/commands/*.md (existing command definitions)
|
||||
- ~/LLM Context/.opencode/commands/*.md (project-local command definitions)
|
||||
- Knowledge/ directories at relevant scopes (initiative, company/personal, global)
|
||||
- Decisions/ directories at relevant scopes (initiative, company/personal, global)
|
||||
- ~/LLM Context/Shared/Templates/decision-template.md (for decision format)
|
||||
|
||||
2. Compare what was learned during this conversation against what is already documented. Identify NEW learnings only -- skip anything already captured. Before proposing any change, read the current content of the target file to verify a previous session has not already applied the same learning.
|
||||
|
||||
Determine which scopes are relevant to this session (e.g., Business/Monizze/, a specific initiative). If ambiguous, ask Sam to confirm the scope before proceeding.
|
||||
|
||||
3. Categorize each learning:
|
||||
- **Preference** -- how Sam likes to work (communication, review style, tooling choices)
|
||||
- **Decision** -- a concrete choice made during this session (tech stack, architecture, process)
|
||||
- **Workflow** -- how Sam interacts with agents, reviews work, iterates
|
||||
- **Correction** -- something the agent got wrong that Sam corrected
|
||||
- **Domain Knowledge** -- a fact, pattern, or observation about a specific domain (pricing, onboarding, competitors, etc.)
|
||||
- **Domain Rule** -- a confirmed pattern that should be applied by default (promoted from hypothesis after 3+ confirmations, or stated directly by Sam)
|
||||
- **Domain Hypothesis** -- a pattern that needs more data before becoming a rule
|
||||
- **Scoped Decision** -- a decision that affects more than today's task and should be logged for future reference
|
||||
|
||||
4. Determine the correct target file for each learning:
|
||||
- Global preferences (apply everywhere) -> `~/.config/opencode/AGENTS.md`
|
||||
- Project-specific rules -> current project's `AGENTS.md`
|
||||
- Context system changes -> `~/LLM Context/AGENTS.md`
|
||||
- Domain context -> appropriate file in `~/LLM Context/`
|
||||
- Domain Knowledge / Rules / Hypotheses -> `Knowledge/[domain].md` at the appropriate scope
|
||||
- If the file exists, add to the correct section (## Rules, ## Hypotheses, or ## Knowledge)
|
||||
- If the file does not exist, create it using the format from LLM Context/AGENTS.md
|
||||
- Check if any existing hypothesis has now been confirmed 3+ times -- propose promotion to Rule
|
||||
- Check if any existing rule was contradicted in this session -- propose demotion to Hypothesis
|
||||
- Scoped Decisions -> `Decisions/YYYY-MM-DD-{topic}.md` at the appropriate scope
|
||||
- Use the template at `Shared/Templates/decision-template.md`
|
||||
- Search existing Decisions/ for prior decisions on the same topic
|
||||
- If replacing a prior decision, populate the ## Supersedes field
|
||||
|
||||
5. Present learnings for review:
|
||||
|
||||
# Learnings - [Date]
|
||||
|
||||
## Summary
|
||||
[1-2 sentence overview of what was learned]
|
||||
|
||||
## Proposed Updates
|
||||
|
||||
### [n]. [Short description]
|
||||
- **Type:** [Preference / Decision / Workflow / Correction / Domain Knowledge / Domain Rule / Domain Hypothesis / Scoped Decision]
|
||||
- **Scope:** [Global / Business/[Company] / Business/[Company]/Initiatives/[Name] / Personal / Personal/Initiatives/[Name]]
|
||||
- **Domain:** [domain name, if applicable -- e.g., pricing, onboarding]
|
||||
- **Learning:** [What was learned]
|
||||
- **Target file:** [Path to the file that should be updated]
|
||||
- **Proposed change:**
|
||||
```
|
||||
[The specific text to add or modify in the target file]
|
||||
```
|
||||
- **Status:** Pending review
|
||||
|
||||
[Repeat for each learning]
|
||||
|
||||
## No Update Needed
|
||||
[List any learnings that are already captured in existing files -- confirm they match]
|
||||
|
||||
6. After presenting the full summary, walk through each proposed change ONE AT A TIME. For each:
|
||||
- Show the change (target file, what will be added/modified)
|
||||
- Ask: "Accept, reject, or modify?"
|
||||
- Wait for Sam's response before moving to the next
|
||||
- Only apply the change after explicit acceptance
|
||||
|
||||
7. For each accepted change, update the target file immediately, then present the next one.
|
||||
|
||||
8. After all changes are reviewed, add a "Last Updated" entry to each modified file with the date and a brief description.
|
||||
|
||||
IMPORTANT:
|
||||
- Never apply changes without Sam's explicit approval
|
||||
- Always go one at a time -- never batch approvals
|
||||
- Be specific -- show exact text to add/modify, not vague suggestions
|
||||
- If a learning contradicts an existing rule, flag the conflict and ask which is correct
|
||||
- Include the source of each learning (what Sam said or did that revealed it)
|
||||
- Skills and commands are valid target files -- if a session revealed a gap or correction in a skill or command, propose an update to that file directly
|
||||
- For knowledge items, always specify which section (Rules / Hypotheses / Knowledge) the entry belongs in
|
||||
- When promoting a hypothesis to a rule, remove it from ## Hypotheses and add it to ## Rules with a note like "Promoted from hypothesis -- confirmed in [sessions/dates]"
|
||||
- When demoting a rule to a hypothesis, remove it from ## Rules and add it to ## Hypotheses with a note like "Demoted -- contradicted by [what happened]"
|
||||
- For scoped decisions, always use the decision template format
|
||||
- When scope is ambiguous, ask Sam before proceeding -- one topic at a time
|
||||
@@ -0,0 +1,81 @@
|
||||
# /task
|
||||
|
||||
Create, update, complete, or list tasks. Single command for all task CRUD operations.
|
||||
|
||||
## Subcommands
|
||||
|
||||
### /task add [details]
|
||||
### /task (no args -- defaults to add)
|
||||
|
||||
Create a new task.
|
||||
|
||||
**Shortcut mode:** `/task add "Title" high due:2026-04-15 initiative:Messaging-System effort:medium`
|
||||
|
||||
**Guided mode** (no args or incomplete): Ask these questions one at a time:
|
||||
1. **Task title** -- short, action-oriented
|
||||
2. **Initiative** -- which initiative does this belong to? (list active initiatives from AGENTS.md, or "Personal", or "None")
|
||||
3. **Priority** -- High / Medium / Low
|
||||
4. **Due date** -- YYYY-MM-DD or TBD
|
||||
5. **Effort** -- Quick (<30 min) / Medium (30 min - 2h) / Deep (2h+)
|
||||
6. **Context** -- paths to context files in ~/LLM Context/ (or "none")
|
||||
7. **Description** -- what needs to be done
|
||||
|
||||
**After gathering info:**
|
||||
- Create file at `todo/YYYY-MM-DD-short-slug.md` using today's date
|
||||
- Use the template from `meta/templates/task-template.md`
|
||||
- Remove the Completed field (not applicable in todo/)
|
||||
- Confirm creation with: "Created: `todo/YYYY-MM-DD-slug.md`"
|
||||
|
||||
### /task update [search-term]
|
||||
|
||||
Modify an existing task.
|
||||
|
||||
1. Search across `todo/`, `ongoing/`, and `blocked/` for a task matching the search term (title match, fuzzy is fine)
|
||||
2. If multiple matches, show them and ask which one
|
||||
3. Show the current task state
|
||||
4. Ask what to update -- offer these options:
|
||||
- Priority
|
||||
- Due date
|
||||
- Effort
|
||||
- Description
|
||||
- Notes (append)
|
||||
- Move to a different status folder
|
||||
- Multiple fields at once
|
||||
5. Apply the update and confirm
|
||||
|
||||
**If status changes:** move the file to the new folder. If moving to `done/`, add Completed date (use `/task done` flow).
|
||||
|
||||
### /task done [search-term]
|
||||
|
||||
Mark a task as completed.
|
||||
|
||||
1. Search across `todo/`, `ongoing/`, and `blocked/` for the task
|
||||
2. Show the current task and ask for confirmation
|
||||
3. Ask: "Any notes to add before closing?"
|
||||
4. Add Completed date (today) to the task file
|
||||
5. Move file to `done/`
|
||||
6. Confirm: "Completed: moved to `done/YYYY-MM-DD-slug.md`"
|
||||
|
||||
### /task list
|
||||
|
||||
Quick flat listing of all open tasks. Lightweight -- no inference, no analysis.
|
||||
|
||||
1. Read all files in `todo/`, `ongoing/`, and `blocked/`
|
||||
2. Output a simple table:
|
||||
|
||||
```
|
||||
| Task | Initiative | Priority | Due | Folder |
|
||||
|------|-----------|----------|-----|--------|
|
||||
| ... | ... | ... | ... | todo/ongoing/blocked |
|
||||
```
|
||||
|
||||
Sorted by priority then due date (same rules as /agenda).
|
||||
|
||||
## Rules
|
||||
|
||||
- All task files live in `~/Workspace/Personal/Tasks/`
|
||||
- Use `meta/templates/task-template.md` as the canonical format
|
||||
- Filename convention: `YYYY-MM-DD-short-slug.md`
|
||||
- When creating: date = today. When moving: keep the original filename (created date doesn't change)
|
||||
- The Completed field only appears in files inside `done/`
|
||||
- When cancelling: move to `cancelled/`, add reason in Notes
|
||||
@@ -0,0 +1,403 @@
|
||||
---
|
||||
name: setup-context-system
|
||||
description: "Guide a person through building a layered AI context system for their coding agent: global/project/initiative context files, index files, knowledge management with Rules and Hypotheses, decision logging, tone and behavior rules, optional discovery methodology, a maintenance command, and an optional offer to install obra's Superpowers. Use when someone wants to set up CLAUDE.md / AGENTS.md context from scratch, stop re-explaining context every session, or replicate a self-maintaining context setup."
|
||||
compatibility: "claude-code, opencode"
|
||||
---
|
||||
|
||||
# Set Up a Layered Context System
|
||||
|
||||
You are guiding a person through building a **layered context system** for their AI coding agent. The goal is a self-maintaining setup where the agent always has the right context, tone, and methodology without the user re-explaining things every session.
|
||||
|
||||
This system has proven components. You teach the **pattern** and the **reasoning** behind each layer, but the user fills in their **own** content. The output is *their* system, not a copy of anyone else's.
|
||||
|
||||
## Core Operating Rules (apply in every phase)
|
||||
|
||||
1. **One question at a time.** Prefer multiple-choice. Never batch questions. Wait for the answer before the next question.
|
||||
2. **Phase gate.** Complete one phase, confirm it with the user, then STOP and ask before starting the next phase. Never run multiple phases in one pass. A user who stops after Phase 1 must have a working system.
|
||||
3. **Diagnostic-first.** When a user can't answer a direct question (e.g., "what tone rules do you want?"), do NOT leave it blank. Ask indirect diagnostic questions and *derive* the answer, then propose it as concrete text for accept/modify/skip.
|
||||
4. **Confirm before write.** Always show a preview of any file you are about to create or edit. Get explicit approval before writing. For bulk content (many files/sections), show 3-5 examples first and get approval before applying to all.
|
||||
5. **Condense, don't dump.** When importing existing content (e.g., from Atlassian), summarize into small targeted files in the system's format. Never paste raw content verbatim.
|
||||
6. **Lazy creation.** Create folders and files only when there is real content to put in them. No empty placeholders, no preemptive structure.
|
||||
7. **Platform variables.** Use the variables set in Phase 0 (`CONTEXT_FILE`, `COMMANDS_DIR`, `HUB_PATH`) everywhere. Never hardcode `CLAUDE.md` or `AGENTS.md`.
|
||||
8. **Verify, don't assume.** Never assume a platform's paths or behavior. Check the filesystem or ask the user. State the source of any path you rely on.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Detect & Orient
|
||||
|
||||
No files are written in this phase. Establish the environment and resume point.
|
||||
|
||||
### Step 0.1 — Detect platform
|
||||
|
||||
Inspect the filesystem to detect which agent platform is in use:
|
||||
- If `~/.claude/` exists → **Claude Code**. Set `CONTEXT_FILE = CLAUDE.md`, `COMMANDS_DIR = ~/.claude/skills/` (Claude Code merges custom commands into skills; a skill at `~/.claude/skills/<name>/SKILL.md` becomes `/<name>`).
|
||||
- If `~/.config/opencode/` exists → **OpenCode**. Set `CONTEXT_FILE = AGENTS.md`, `COMMANDS_DIR = ~/.config/opencode/command/`. Skills live at `~/.config/opencode/skills/<name>/SKILL.md`.
|
||||
- If both or neither exist, ask the user: "Which agent are you setting this up for — Claude Code, OpenCode, or something else?" and set the variables accordingly. If "something else," ask the user for their global config path and the filename their agent reads for project instructions.
|
||||
|
||||
Announce the detected platform and the file names you'll use, e.g.:
|
||||
> "Detected **Claude Code**. Global preferences go in `~/.claude/CLAUDE.md`, project context in `CLAUDE.md` files, commands/skills in `~/.claude/skills/`."
|
||||
|
||||
### Step 0.2 — Locate the context hub
|
||||
|
||||
Ask: "Where do you want your **context hub** to live? This is the folder that holds your business/personal context, knowledge, and decisions."
|
||||
- Offer a sensible default (e.g., `~/Context` or `~/LLM Context`).
|
||||
- Set `HUB_PATH` to the chosen folder.
|
||||
|
||||
### Step 0.3 — Detect resume point
|
||||
|
||||
Check which layers already exist on disk and report the user's current state:
|
||||
- Does the global preferences file exist and contain real rules?
|
||||
- Does `HUB_PATH/CONTEXT_FILE` exist?
|
||||
- Do index files exist (e.g., `profile.md`)?
|
||||
- Do `Knowledge/` or `Decisions/` folders exist anywhere under `HUB_PATH`?
|
||||
- Do maintenance commands exist in `COMMANDS_DIR`?
|
||||
|
||||
Report: "You're at **Phase N**. Here's what exists, here's what's next." Then ask whether to start/continue there.
|
||||
|
||||
### Step 0.4 — Explain the model (briefly)
|
||||
|
||||
Before building, give a 4-5 line explanation of the layered model so the user understands what they're building:
|
||||
|
||||
> **The three layers:**
|
||||
> 1. **Global** (`CONTEXT_FILE` in your global config) — how the agent should behave on *every* project: tone, planning protocol, feedback style.
|
||||
> 2. **Project** (`CONTEXT_FILE` at a project root) — what *this* project is, where its context lives, how to navigate it.
|
||||
> 3. **Initiative** (`CONTEXT_FILE` inside a sub-folder) — context for one specific piece of work.
|
||||
>
|
||||
> **Plus:** index files (navigation to small context files), Knowledge files (learned rules), Decision logs, and a maintenance command that keeps it all current.
|
||||
|
||||
Then proceed to Phase 1 only after the user confirms.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Essentials (the must-have working system)
|
||||
|
||||
Goal: a functioning system after this phase alone. Produces the **global preferences file**, the **project hub context file**, and the **tone/behavior rules**.
|
||||
|
||||
### Step 1.0 — Propose universal default rules
|
||||
|
||||
Start by offering a curated set of rules that work well for most people. Present them grouped, and ask the user to **accept / modify / skip each one** (don't force any). These are defaults, not mandates — the user's answers override them.
|
||||
|
||||
Present this set (group as shown):
|
||||
|
||||
**Communication**
|
||||
- No affirmative emphasis ("You're right", "Excellent idea", "Great point") — stay factual.
|
||||
- Keep responses concise; don't restate what the user already knows.
|
||||
- Use bullet points for feedback and summaries.
|
||||
- When showing diffs, include a summary of what changed and why.
|
||||
|
||||
**Planning**
|
||||
- Discuss strategy and get approval before making changes.
|
||||
- A prior "go ahead" doesn't carry to a new design decision — each new decision needs its own approval.
|
||||
- Plan at the high level first, then drill into task detail.
|
||||
- When evaluating options, document the excluded ones with reasoning, not just the pick.
|
||||
|
||||
**Feedback**
|
||||
- Give direct feedback and critiques — no hedging.
|
||||
- Challenge assumptions and claims rather than taking them at face value.
|
||||
|
||||
**Grounding & verification**
|
||||
- Ground factual claims in sources or the user's explicit input; state when no source exists rather than filling the gap.
|
||||
- Never assume the capabilities or behavior of external platforms/tools — verify (docs, tooling, or ask) before relying on them.
|
||||
|
||||
**Work style**
|
||||
- Clean up temp files and abandoned work when done.
|
||||
- Don't assign ownership, names, or responsibilities to items unless asked.
|
||||
|
||||
After the user accepts/modifies/skips these, move to diagnostics for anything NOT already covered.
|
||||
|
||||
### Step 1.1 — Communication & tone gaps (diagnostic)
|
||||
|
||||
For anything the default set didn't settle, ask diagnostics one at a time and derive rules. Skip questions already answered by Step 1.0. Examples:
|
||||
|
||||
- "Paste a recent AI reply that annoyed you, or describe what bugs you about how AI assistants talk." → concision / anti-fluff specifics.
|
||||
- "Should the agent refer to you by name or use 'you'? Any pronoun conventions for context files?" → naming conventions (this is personal — derive, don't assume).
|
||||
- "Any formatting preferences beyond bullet points — tables, headers, code blocks?" → formatting default.
|
||||
|
||||
Fold the answers into the **Communication Style** section. Accept/modify/skip each addition.
|
||||
|
||||
### Step 1.2 — Planning & feedback gaps (diagnostic)
|
||||
|
||||
For anything not covered by Step 1.0, ask diagnostics, then derive:
|
||||
- "Should the agent ask clarifying questions one at a time, or batch them?" → question cadence.
|
||||
- "For bulk edits (many files/rows), should the agent show a few examples first and get approval before applying to all?" → bulk-edit rule.
|
||||
- "Should the agent ever state facts it isn't sure of, or always flag uncertainty / ask?" → grounding specifics (if not settled in 1.0).
|
||||
|
||||
Fold into the **Planning Protocol** and **Feedback Style** sections. Accept/modify/skip.
|
||||
|
||||
### Step 1.3 — Work style gaps (diagnostic, light)
|
||||
|
||||
Step 1.0 already proposed cleanup and no-unsolicited-ownership defaults. Ask only what's left:
|
||||
- "Do you work iteratively (structure first, then refine) or all-at-once?"
|
||||
- Any other working-style preference the defaults missed?
|
||||
|
||||
Fold into the **Work Style** section.
|
||||
|
||||
### Step 1.4 — Write the global preferences file
|
||||
|
||||
Assemble the approved sections into `CONTEXT_FILE` at the global config location. Structure:
|
||||
|
||||
```markdown
|
||||
# [Name]'s Global Agent Preferences
|
||||
|
||||
These preferences apply to all projects and sessions.
|
||||
|
||||
## Communication Style
|
||||
[accepted defaults + derived bullets]
|
||||
|
||||
## Planning Protocol
|
||||
[accepted defaults + derived bullets]
|
||||
|
||||
## Feedback Style
|
||||
[accepted defaults + derived bullets]
|
||||
|
||||
## Work Style
|
||||
[accepted defaults + derived bullets]
|
||||
|
||||
## Core Context Hub
|
||||
[Name] maintains context files at `HUB_PATH`. Consult index files for navigation; load only what the task needs.
|
||||
|
||||
## Last Updated
|
||||
[YYYY-MM-DD] - Initial creation via setup-context-system
|
||||
```
|
||||
|
||||
Show the full file as a preview. Write only after approval.
|
||||
|
||||
### Step 1.5 — Write the project hub context file
|
||||
|
||||
Create `HUB_PATH/CONTEXT_FILE` explaining the context system itself:
|
||||
|
||||
```markdown
|
||||
# Context Hub - Agent Instructions
|
||||
|
||||
This folder holds [Name]'s context files. Global behavior preferences live in the global config; this file covers the context system and file organization.
|
||||
|
||||
## Context System
|
||||
Index files point to small, targeted context files. Treat indexes as navigation, not content to load wholesale.
|
||||
|
||||
## How to Load Context
|
||||
1. Identify the task domain.
|
||||
2. Consult the relevant index file.
|
||||
3. Load only the specific files needed.
|
||||
|
||||
## Lazy Creation
|
||||
Folders and files are created only when there is content to store. No preemptive structure.
|
||||
|
||||
## Last Updated
|
||||
[YYYY-MM-DD] - Initial creation
|
||||
```
|
||||
|
||||
Preview, approve, write. **Phase gate: confirm Phase 1 is done, then ask before Phase 2.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Index Files + Granular Context
|
||||
|
||||
Goal: the navigation layer plus the first real context files. Only proceed when the user has actual content worth splitting out.
|
||||
|
||||
### Step 2.1 — Identify domains (diagnostic)
|
||||
|
||||
Ask: "What topics do you find yourself re-explaining to an AI again and again?" One at a time, build a short list (e.g., a product, a company, a person, a recurring writing task). These become granular context files.
|
||||
|
||||
If the user struggles, ask diagnostics: "What did you have to explain in your last 3 AI sessions that you'd already explained before?"
|
||||
|
||||
### Step 2.2 — Create an index file
|
||||
|
||||
Create an index (e.g., `HUB_PATH/profile.md`) with a When-to-Load table:
|
||||
|
||||
```markdown
|
||||
# [Profile/Index Name]
|
||||
|
||||
Index pointing to context files. Navigation only — load specific files as needed.
|
||||
|
||||
| File | Purpose | When to Load |
|
||||
|------|---------|--------------|
|
||||
| `[file].md` | [purpose] | [trigger] |
|
||||
|
||||
## Last Updated
|
||||
[YYYY-MM-DD] - Initial creation
|
||||
```
|
||||
|
||||
### Step 2.3 — Create 2-3 starter context files
|
||||
|
||||
For each domain the user has real content for, draft a small focused file. Show as preview, approve, write. Add a row to the index for each. Do NOT create files for domains the user can't fill yet — note them for later.
|
||||
|
||||
**Phase gate: confirm, then ask before Phase 2.5 or Phase 3.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.5 — Atlassian Import (OPTIONAL)
|
||||
|
||||
Offer this only after Phase 2 (imported content needs a home). Skippable.
|
||||
|
||||
### Step 2.5.1 — Detect, and offer to set up the MCP
|
||||
|
||||
Check whether Atlassian MCP tools are available in this session.
|
||||
- **Available** → proceed to Step 2.5.2.
|
||||
- **Not available** → offer to set it up: "Connecting an Atlassian (Confluence/Jira) integration lets me pull your existing docs straight into context files. Want to set it up now?"
|
||||
|
||||
If the user wants to set it up, give the install method for the **detected platform** (verify the current method against the platform's MCP docs — methods change; do not hardcode from memory). The Atlassian remote MCP endpoint is `https://mcp.atlassian.com/v1/mcp`.
|
||||
|
||||
- **OpenCode** — add to the user's `opencode.json` under `mcp`, then authenticate:
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"atlassian": { "type": "remote", "url": "https://mcp.atlassian.com/v1/mcp" }
|
||||
}
|
||||
}
|
||||
```
|
||||
Then run `opencode mcp auth atlassian` to complete the OAuth flow. (Source: https://opencode.ai/docs/mcp-servers)
|
||||
- **Claude Code** — run:
|
||||
```bash
|
||||
claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp
|
||||
```
|
||||
Then run `/mcp` and follow the browser login to complete OAuth. (Source: https://docs.claude.com/en/docs/claude-code/mcp)
|
||||
- **Other platforms** — point the user to that platform's MCP-server docs; the endpoint is the same.
|
||||
|
||||
Present the config/command and let the user run it — do not edit their MCP config or run auth silently. OAuth requires a browser step the user must complete. After setup, the Atlassian tools load on the next session (or after re-auth); if they aren't available in the current session yet, mark this step as deferred and tell the user to re-run Phase 2.5 once connected.
|
||||
|
||||
If the user declines setup, mark as deferred and continue.
|
||||
|
||||
### Step 2.5.2 — Scope the pull
|
||||
|
||||
Ask one at a time:
|
||||
- "Is there a Confluence space, set of pages, or Jira project worth importing as context?"
|
||||
- For Confluence: which space or page tree?
|
||||
- For Jira: which project, and what context do you want from it (epics, project conventions)?
|
||||
|
||||
### Step 2.5.3 — Map to structure (preview before fetching)
|
||||
|
||||
Propose where imported content lands BEFORE fetching:
|
||||
- A team handbook space → several granular context files under `HUB_PATH` + index entries.
|
||||
- A project's docs → an initiative-level context file.
|
||||
Show the mapping. Get approval.
|
||||
|
||||
### Step 2.5.4 — Import as condensed drafts
|
||||
|
||||
Fetch, then condense into the system's small-file format (not verbatim). For large spaces, show 3-5 condensed examples first and get approval before doing the rest. Preview each target file, approve, write. Update indexes.
|
||||
|
||||
### Step 2.5.5 — Seed knowledge
|
||||
|
||||
Note any recurring patterns spotted during import (e.g., a documented pricing or naming convention). Offer them as starter Rules for Phase 3.
|
||||
|
||||
**Phase gate: confirm, then ask before Phase 3.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Knowledge & Decisions
|
||||
|
||||
Goal: the learning layer. Only build when the user has patterns or decisions worth recording.
|
||||
|
||||
### Step 3.1 — Explain the Knowledge format
|
||||
|
||||
Knowledge files capture learned patterns at three scopes (initiative → company/project → global). Format:
|
||||
|
||||
```markdown
|
||||
# [Domain Name]
|
||||
|
||||
## Rules
|
||||
<!-- Confirmed patterns — apply by default -->
|
||||
|
||||
## Hypotheses
|
||||
<!-- Need more data — test when opportunity arises. Promote to Rules at 3+ confirmations. -->
|
||||
|
||||
## Knowledge
|
||||
<!-- Facts and patterns observed -->
|
||||
```
|
||||
|
||||
Explain the mechanics: hypotheses get promoted to Rules after 3+ confirmations; Rules get demoted to Hypotheses when contradicted. The maintenance command (Phase 4) is what actually moves entries between these sections over time.
|
||||
|
||||
### Step 3.2 — Seed a first Knowledge file
|
||||
|
||||
Ask: "What's one rule you already know is true in a domain you work in?" Capture it as a Rule in `Knowledge/[domain].md` at the right scope. Use any patterns seeded in Phase 2.5. Preview, approve, write (lazy creation — only if there's real content).
|
||||
|
||||
### Step 3.3 — Set up the Decision log
|
||||
|
||||
Explain: decisions that affect more than one task get logged so they aren't re-litigated. Provide the template at `HUB_PATH/Shared/Templates/decision-template.md` (adjust the location to wherever the user keeps shared templates under their hub):
|
||||
|
||||
```markdown
|
||||
# Decision: {what was decided}
|
||||
|
||||
## Context
|
||||
{Why this came up}
|
||||
|
||||
## Alternatives Considered
|
||||
{What else was on the table, with brief pros/cons}
|
||||
|
||||
## Reasoning
|
||||
{Why this option won}
|
||||
|
||||
## Trade-offs Accepted
|
||||
{What was given up}
|
||||
|
||||
## Supersedes
|
||||
{Link to prior decision if replacing one, or "None"}
|
||||
```
|
||||
|
||||
Explain the 3-level scoping (initiative → company/project → global) and the file-naming convention `Decisions/YYYY-MM-DD-{topic}.md`. Create the template file; create actual Decisions/ folders lazily.
|
||||
|
||||
**Phase gate: confirm, then ask before Phase 4.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Methodology & Maintenance Commands
|
||||
|
||||
Goal: the self-maintaining loop and optional discovery methodology.
|
||||
|
||||
### Step 4.1 — Optional discovery methodology
|
||||
|
||||
Ask: "Do you do product discovery or research work where a methodology would help (e.g., Teresa Torres' Continuous Discovery — outcomes over outputs, opportunity solution trees, regular interviews)?"
|
||||
- If yes → append a **Product Discovery Methodology** block to the global preferences file, scaled to how they work.
|
||||
- If no → skip.
|
||||
|
||||
### Step 4.2 — The maintenance command (the key loop)
|
||||
|
||||
This is what keeps the system alive. Create a `/learnings`-style command in `COMMANDS_DIR` that, at the end of a session:
|
||||
1. Reviews the conversation for new preferences, decisions, domain knowledge, corrections.
|
||||
2. Compares against existing context files (reads them first to avoid duplicates).
|
||||
3. Categorizes each learning (Preference / Decision / Workflow / Correction / Domain Knowledge / Rule / Hypothesis).
|
||||
4. Proposes the exact target file and the exact text to add.
|
||||
5. Walks through each proposed change ONE AT A TIME for accept/reject/modify.
|
||||
6. Applies only approved changes; adds a "Last Updated" entry.
|
||||
7. Handles Knowledge promotion/demotion:
|
||||
- Before proposing, check whether any existing Hypothesis was confirmed again this session. If it reaches 3+ confirmations, propose promoting it to a Rule (move it to `## Rules` with a note: "Promoted — confirmed in [dates/sessions]").
|
||||
- Check whether any existing Rule was contradicted this session. If so, propose demoting it to a Hypothesis (move it to `## Hypotheses` with the contradiction noted).
|
||||
|
||||
This closes the loop with Phase 3: the Knowledge format defines Rules vs Hypotheses; this command is what actually moves entries between them over time.
|
||||
|
||||
Draft the command file, preview, approve, write.
|
||||
|
||||
### Step 4.3 — Optional initiative command
|
||||
|
||||
Ask: "Do you run multi-step initiatives or projects that would benefit from a scaffolding command?" If yes, draft a `/create-initiative`-style command that interviews the user and creates an initiative folder with its own `CONTEXT_FILE`, overview file, and index entry.
|
||||
|
||||
### Step 4.4 — Optional: install Superpowers
|
||||
|
||||
[Superpowers](https://github.com/obra/superpowers) (by obra) is a composable skills library that adds a development methodology — brainstorming → writing-plans → TDD → subagent-driven development — that triggers automatically. It complements this context system: this skill gives the agent *context*, Superpowers gives it *process*.
|
||||
|
||||
First, **detect** whether it's already installed before offering:
|
||||
- OpenCode → check for `~/.config/opencode/skills/` entries from superpowers (e.g., a `brainstorming` skill) or a superpowers plugin in `~/.config/opencode/`.
|
||||
- Claude Code → check for a superpowers plugin/skills under `~/.claude/`.
|
||||
- If already present, say so and skip.
|
||||
|
||||
If not installed, ask: "Want to install Superpowers? It adds an automatic spec → plan → TDD workflow." If yes, give the install method for the **detected platform** (verify against the current Superpowers README — methods change; do not hardcode from memory):
|
||||
- **Claude Code:** `/plugin install superpowers@claude-plugins-official` (official marketplace), or via `obra/superpowers-marketplace`.
|
||||
- **OpenCode:** tell the agent: "Fetch and follow instructions from `https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md`".
|
||||
- **Other platforms** (Codex, Cursor, Copilot CLI, Gemini CLI): point the user to the install section of the Superpowers README, since each differs.
|
||||
|
||||
Do not run the install silently — present the command/instruction and let the user run it. This skill only *offers and points*; it does not modify the user's plugin setup without consent.
|
||||
|
||||
**Phase gate: confirm. System complete.**
|
||||
|
||||
---
|
||||
|
||||
## After Completion
|
||||
|
||||
Summarize what was built and how to use it:
|
||||
1. **Global preferences** at the global config — applies everywhere.
|
||||
2. **Project hub** at `HUB_PATH` — explains the system; agent loads it when working there.
|
||||
3. **Index files** — navigation to granular context.
|
||||
4. **Knowledge / Decisions** — the learning layer; grows lazily.
|
||||
5. **Maintenance command** — run it at the end of sessions to keep everything current.
|
||||
6. **Superpowers** (if installed) — provides the development process layer alongside this context layer.
|
||||
|
||||
Remind them: the system is meant to grow incrementally. Run the maintenance command regularly; add Knowledge and Decisions only when there's real content. Re-run this skill anytime to add a phase they skipped.
|
||||
Reference in New Issue
Block a user