How I use AI - LLMs

This documents my setup for using LLM-powered coding agents (specifically OpenCode with Claude) as a day-to-day software engineering tool. The system is built around three ideas:

1. Persistent context -- agent instructions, well-known locations, and slash commands that survive across sessions
2. Structured work tracking -- gameplan files that act as the source of truth for multi-session tasks
3. Git as the backbone -- everything meaningful is version-controlled, including gameplans and research notes

---

Directory Layout

All paths are fixed. The agent knows them and doesn't need to ask.

Path	Purpose	Git-tracked
~/workspace/	Parent for all project repos	n/a
~/workspace/tmp/	Throwaway clones (always shallow)	n/a
~/workspace/gameplans/	Gameplan files for active work	yes
~/llm-notes/	Research output and notes	yes
~/.config/opencode/	Agent configuration	no

The gameplans and llm-notes directories are git repos. The agent commits to them after every modification.

---

Agent Configuration

Global Instructions (AGENTS.md)

Lives at ~/.config/opencode/AGENTS.md. Sets baseline rules for every session:

# Global Agent Guidelines

## Well-Known Locations
<table of paths above>

## Safety First
- Always ask before making file modifications
- Never execute destructive commands without explicit approval
- Preserve existing code structure and conventions

## Code Changes
- Explain proposed changes before implementing them
- Make minimal, focused changes
- Avoid refactoring unrelated code unless asked

## Git Operations
- Never force push or rewrite history without approval
- Always show the diff before committing
- Write clear, descriptive commit messages

## Communication
- When uncertain, ask for clarification
- Write research output into ~/llm-notes/ and commit after writing

It also defines specialized agent types (research, review) with scoped instructions for what they can and cannot do.

Per-Repo Instructions (AGENTS.md in repo root)

Each repository can have its own AGENTS.md that provides repo-specific context: architecture overview, design patterns, anti-patterns to flag, testing expectations, and deployment details. The agent loads this automatically when working in that repo.

Example structure for a repo AGENTS.md:

# Agent Guide for <Project>

## Repository Overview
<what this project does, key technologies>

## Common Design Patterns
<patterns the agent should follow, with code examples>

## What to Ignore in Reviews
<things that look wrong but are intentional>

## What to Focus On
<security, correctness, resource management, testing>

## Testing Expectations
<what tests to run, how to run them, what frameworks are used>

## Common Anti-Patterns to Flag
<things the agent should call out>

---

Slash Commands

Custom commands live in ~/.config/opencode/commands/ as markdown files. They're invoked with /command-name in the chat.

/init_workspace

Sets up a new work environment for a task:

1. Creates a git worktree from the target repo
2. Creates a gameplan file in ~/workspace/gameplans/

---
description: Initialize a git worktree workspace with a gameplan file
---

## Arguments
- **identifier**: A project name
- **primary-repo**: The repository to create the worktree from

## Process
1. Parse arguments, validate the repo exists at ~/workspace/<repo>
2. Create a git worktree: `git worktree add -b <branch> <path> origin/main`
3. Create a gameplan file at ~/workspace/gameplans/gameplan-<identifier>.md

## Gameplan Template
# Gameplan: <IDENTIFIER>

## Information
- **Workspace**: ~/workspace/<repo>-<identifier>
- **Branch**: <branch-name>
- **Created**: <date>

## Objective
<what this work is about>

## Tasks
- [ ] Task 1
- [ ] Task 2

## Open Questions
<blockers or ambiguities>

## Progress Log
### <date>
- Initialized workspace

## Notes

/start_work

Picks up an existing gameplan and works through it:

---
description: Start working on a project using an existing gameplan file
---

## Arguments
- **gameplan-identifier**: A project name

## Process

### 1. Locate and Read Gameplan
- Find gameplan file at ~/workspace/gameplans/gameplan-<identifier>.md
- Extract workspace path, branch, tasks, open questions

### 2. Validate Workspace
- Verify the worktree exists and is on the correct branch
- Check for uncommitted changes

### 3. Understand Current State
- Review completed tasks
- Identify next pending task(s)
- Surface any blockers

### 4. Execute Tasks
For each pending task:
1. Mark task as in-progress
2. Analyze what needs to be done
3. Spin off specialized agents (explore, research, implement, review)
4. Implement the changes
5. **Update the gameplan and commit it**
6. Ask user before committing project code

### 5. Update Gameplan (after every completed task)
1. Mark completed tasks with [x]
2. Add Progress Log entry with date and summary
3. Update Notes with discoveries
4. Add new tasks if scope expanded
5. **Commit the gameplan**:
   cd ~/workspace/gameplans
   git add gameplan-<identifier>.md
   git commit -m "update gameplan-<identifier>: mark <task> complete"

### 6. Checkpoint with User
- Summarize what was accomplished
- Show updated task status
- Ask whether to continue, pause, or adjust

/commit

Creates a commit with a structured message:

---
description: Create a commit following structured commit guidelines
---

## Commit Message Format
<type>: <description>

<body explaining WHY>

## Types
feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

## Instructions
1. Check git status and staged changes
2. If nothing staged, offer to stage unstaged changes
3. **Fixup detection**: Check if the change is a correction to an
   existing commit on the branch. If so, suggest --fixup instead
4. Show the full diff before proposing a message
5. Draft the message, show it for approval
6. Commit using heredoc (not -m) for multi-line messages

## Commit Strategy
- Each commit should be a complete unit of work
- It should compile independently
- It should be independently reviewable (~200 lines ideal)

/research

Researches a topic using available tools and writes output to ~/llm-notes/:

---
description: Research a topic using available sources
---

## Process
1. Search available sources (docs, code, issue trackers)
2. Create a structured report with:
   - Executive Summary
   - Key Findings
   - Related Systems/Components
   - Open Questions
3. Save to ~/llm-notes/<topic>-research.md
4. Commit the file

---

The Gameplan Workflow

flowchart TD
    A["/init_workspace repo"] --> B["Agent creates worktree + gameplan"]
    B --> C["Agent commits gameplan"]
    C --> D{"Human reviews gameplan"}
    D -->|Edits needed| E["Human edits gameplan directly"]
    E --> D
    D -->|Approved| F["/start_work"]
    F --> G["Agent reads gameplan, identifies next task"]
    G --> H["Agent works on task"]
    H --> I["Agent updates gameplan, commits it"]
    I --> J{"More tasks?"}
    J -->|Yes| K{"Checkpoint: continue?"}
    K -->|Yes| G
    K -->|Pause| L["Session ends, gameplan is up to date"]
    J -->|No| M["All tasks complete"]
    M --> N["/commit"]
    N --> O{"Fixup or new commit?"}
    O -->|Fixup| P["git commit --fixup"]
    O -->|New| Q["Structured commit message"]

    style D fill:#f9f,stroke:#333
    style K fill:#f9f,stroke:#333
    style O fill:#f9f,stroke:#333

There is an intentional handoff between /init_workspace and /start_work. After the agent generates the gameplan, I review it before any implementation begins. The gameplan is the agent's proposed plan of attack -- tasks, ordering, approach -- and it's often wrong or incomplete on the first pass. I'll edit the file directly to reorder tasks, add missing steps, refine the approach, or flag things the agent missed. Only after I'm satisfied with the plan do I run /start_work.

This is the most important human-in-the-loop moment in the whole workflow. The agent is good at executing a plan but not always great at making one. Letting it charge ahead with a bad plan wastes more time than reviewing it upfront.

Why gameplans

Why gameplans instead of just TODO comments or issue trackers:

• Session persistence -- the LLM context resets between sessions, but the gameplan file survives
• Audit trail -- the progress log shows what was done and when
• Resumability -- a new session can pick up exactly where the last one left off
• Version controlled -- git history shows how the plan evolved
• Human-editable -- it's just a markdown file, easy to restructure by hand before handing back to the agent

---

Permission Model

The agent config (opencode.jsonc) defines what the agent can run without asking. The philosophy:

• Read-only commands: always allowed (git log, git diff, ls, grep, go test, etc.)
• Build and lint: allowed (go build, npm run build, cargo check, etc.)
• Write operations: require approval (git commit, git push, file edits outside tmp)
• Destructive operations: always require approval (git reset, rm outside tmp, force push)

This is configured per-tool (bash, edit, external_directory) with glob patterns:

{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git log *": "allow",
      "git diff *": "allow",
      "go test *": "allow",
      "go build *": "allow",
      // ...
    },
    "edit": {
      "*": "ask",
      "AGENTS.md": "allow",
      "/tmp/**": "allow"
    }
  }
}

---

Key Principles

1. The agent doesn't guess paths. Well-known locations are defined once and referenced everywhere.

2. Everything gets committed. Gameplans, research notes, code changes -- if it matters, it's in git.

3. Gameplans are the source of truth. Not the chat history, not the issue tracker. The gameplan file is what the agent reads to understand where things stand.

4. Fixups over fix commits. When a change corrects an earlier commit on the same branch, use --fixup and rebase later instead of adding a "fix typo" commit.

5. Ask before writing, always show before committing. The agent explains what it wants to do, shows the diff, and waits for approval.

6. Specialized agents for specialized tasks. Exploration, research, implementation, and review are handled by different agent configurations with different scopes.