Skip to content

refactor(ai): streamline agent harness configuration #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stephendolan merged 4 commits into from
Jul 24, 2026
Merged

refactor(ai): streamline agent harness configuration #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
066d28f
feat(ai): add 1Password MCP integration
stephendolan Jul 17, 2026
acee6c2
fix(tuple): rebuild post-call-activity on Fortress proposal tools
stephendolan Jul 20, 2026
3efc891
refactor(ai): prune personal skill suite
stephendolan Jul 24, 2026
137b32e
Merge remote-tracking branch 'origin/main' into refactor/prune-skills
stephendolan Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ai/.claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "stephendolan",
"version": "2.7.0",
"version": "2.9.0",
"description": "Personal agents and skills for development workflows, code review, architecture analysis, and domain expertise.",
"author": {
"name": "Stephen Dolan",
Expand Down
92 changes: 10 additions & 82 deletions ai/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,9 @@ When reviewing your own work, ask: *Am I adding complexity because it's necessar

## Sub-Agent Delegation

**Delegate to sub-agents proactively.** Sub-agents preserve your context window, enable parallel execution, and start with fresh perspective.

When work decomposes into independent pieces, delegate each to a sub-agent and run them in parallel.

In runtimes with stricter dispatch policies, proactive delegation applies when
the user invoked a workflow that authorizes delegation (such as Ship) or
explicitly asked for subagents, delegation, or parallel agent work. Otherwise,
apply the relevant role in the main thread.

**Patterns:**

- Use `run_in_background: true` for tasks that don't block your main work
- When delegating to parallel sub-agents, no two agents should edit the same file. If edits to the same file are needed, serialize them or assign a single owner.
- The built-in `Explore` agent inherits the main session's model, capped at Opus. If any built-in subagent still fails with "Prompt is too long" in a session with many MCP servers loaded, pass `model: sonnet` (or `opus`) on the Agent invocation to escape, or fall back to `general-purpose`.
Use sub-agents when the user or an invoked workflow authorizes delegation and
the work benefits from independent context or parallel execution. Give each
agent a bounded question or file ownership; serialize edits to the same file.

### Runtime Portability

Expand All @@ -42,42 +31,6 @@ non-Claude runtimes.
- Spawn only when the user explicitly asks for subagents, delegation, or
parallel agent work. Otherwise, apply the role in the main thread.

### Quick Reference

| Workflows | Purpose |
| --------------------------------- | --------------------------------------------- |
| `/commit` | Commit with conventional message (why > what) |
| `/create-pr` | Create PR with concise description |
| `/ship` | Autonomous end-to-end feature development |
| `/refine-implementation` | Multi-pass code review before commit |
| `/examine-architecture` | Evaluate codebase for structural problems |
| `/improve-codebase-architecture` | Find deepening opportunities informed by ADRs |
| `/address-pr-review` | Resolve PR review comments |
| `/review-dependabot` | Analyze and merge Dependabot PRs |
| `/grill-me` | Interrogate a plan to resolve every open decision |

| Agents | Purpose |
| ----------------------- | --------------------------------------------- |
| `code-explorer` | Trace execution paths, map dependencies |
| `code-architect` | Design feature architectures |
| `code-reviewer` | Review for bugs, security, conventions |
| `code-refiner` | Simplify complexity, improve maintainability |
| `architecture-reviewer` | Evaluate brittleness, complexity, coupling |
| `plan-refiner` | Validate plans, suggest simpler approaches |
| `pr-comment-reviewer` | Evaluate PR comments for actionability |
| `design-refiner` | Iteratively refine frontend designs |
| `documentation-refiner` | Maintain Markdown files and developer docs |
| `skeptic` | Challenge conclusions before reaching user |

| Domain Skills | Trigger |
| ------------------------ | ----------------------------------- |
| `frontend-design` | Building web interfaces |
| `writing-documentation` | Updating docs |
| `mom-test` | Customer-discovery interview design |
| `drama-triangle` | Communication and conflict analysis |
| `task-management` | GTD workflow (OmniFocus) |
| `notes-knowledge-base` | Stephen's Obsidian notes knowledge base |

## Documentation Standards

**Write timeless documentation.** Describe what IS, not what WAS.
Expand All @@ -89,32 +42,11 @@ Avoid temporal references: "vs previous", "used to be X", "now uses Y", "the new
## Personal Knowledge Base

Stephen's personal knowledge base lives at `/Users/stephen/Obsidian/Notes`.

When working there or answering questions from that vault:

- Read the vault-local `AGENTS.md` first; it is the canonical operating contract.
- Use the `notes-knowledge-base` skill if available.
- Treat the vault root as the maintained knowledge-base surface.
- Keep top-level additions within the allowed surfaces named by the vault-local `AGENTS.md`; update that contract if a new root surface is genuinely needed.
- Search the vault root before broader filesystem search.
- Use `Sources/` only for provenance and preserved source text that belongs inside the vault.
- Treat the vault as a wiki, not an app/tool/transcript archive. Do not leave one-off scripts, generated call pages, raw transcript dumps, watcher files, prompts, pid files, or regeneration pipelines in the vault.
- For Tuple call work, raw evidence lives outside Obsidian at `~/Documents/Tuple Calls`. Read the external dated call folders, then update maintained synthesis pages such as `Topics/Tuple Calls.md`, project pages, people/entities, account pages, decision ledgers, and customer-signal pages.
- Treat source capture as incomplete until durable facts are promoted into maintained synthesis pages.
- Prefer many small, named pages over massive aggregate docs. Folder indexes are navigation pages only; durable people, accounts, projects, decisions, concepts, and reusable answers should each get their own page.
- Name knowledge-base pages after the real thing, not the source role. Use pages like `Entities/People/Jack Hannah.md` or `Entities/Accounts/Rentvine.md`, not buckets like "participants."
- Prefer the `obsidian` CLI for Obsidian-native checks when available; otherwise fall back to the app binary as documented in the vault.
- Do not create todos, reminders, or execution queues in notes. Capture real tasks in Fortress.
Read its `AGENTS.md` before working there; it is the single operating contract.
Use `notes-knowledge-base` when available to route queries and maintenance.

## Development Workflow

### Quality Gates

- **Plan** -> plan-refiner approves -> **Implement**
- **Code** -> code-refiner approves -> **Commit**
- **Commit** -> `/commit` -> **Continue/PR**
- **PR** -> `/create-pr` -> **Done**

### External Review Gate

Use a fresh-context independent reviewer for high-risk plans and risky diffs.
Expand All @@ -124,16 +56,13 @@ specialist reviewer such as `ce-adversarial-reviewer`, or a `default` subagent
loaded with the relevant plan/diff and review criteria when the specialist role
is not exposed.

- Good targets: high-risk plans before implementation, architecture reviews with cross-cutting findings, and risky diffs before commit
- Bad targets: small edits, routine refactors, or cases where local reviewers already agree and the risk is low

### State Management for Long Tasks
- Good targets: high-risk plans, cross-cutting architecture conclusions, and risky diffs.
- Routine edits and settled local refactors do not need an independent gate.

For complex work spanning multiple sessions:
### Git Delivery

- Use structured formats (JSON) for test results and task status
- Create setup scripts (`init.sh`) for graceful restarts across sessions
- Track progress in files and review filesystem state when resuming
- Write conventional, imperative commit subjects that explain intent; use a body when the reason or trade-off is not obvious.
- Keep PR descriptions concise and problem-focused. Omit file inventories and testing sections unless they convey material information.

## Code Quality Standards

Expand Down Expand Up @@ -167,7 +96,6 @@ Built-in Grep and Glob tools are primary for search. When bash is needed (piping

### Personal Productivity CLIs

- **of** (OmniFocus CLI) - Task management, GTD workflow
- **obsidian** (Obsidian CLI) - Obsidian vault search, links, tags, properties, and capture
- **helpscout** (HelpScout CLI) - Customer support for Tuple
- **ynab** (You Need A Budget CLI) - Personal budgeting
Expand Down
214 changes: 43 additions & 171 deletions ai/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,201 +1,73 @@
# AI Coding Agent Configuration
# AI Agent Configuration

Custom agents, skills, and workflows for Claude Code, Codex, and other agent
runtimes.
Stephen's shared Claude Code and Codex configuration: a small set of personal
skills, runtime-neutral agent roles, hooks, and MCP server definitions.

## Install as a Plugin
## Install

This repository serves as a Claude Code plugin marketplace. To install:

```bash
# Add the marketplace
```text
/plugin marketplace add stephendolan/dotfiles

# Install the plugin
/plugin install stephendolan@dotfiles
```

In Claude, skills become available as `/stephendolan:commit`,
`/stephendolan:create-pr`, etc. In Codex, use the installed skills directly
and generate native subagent roles from the canonical markdown definitions.
Claude exposes plugin skills under `/stephendolan:<name>`. Codex uses the
installed skills and generated native roles.

### Local Development
For local Claude development:

```bash
# Test locally without installing
claude --plugin-dir ./ai
```

# Pick up changes during development
/reload-plugins
Reload Claude plugins after edits with `/reload-plugins`. Regenerate Codex
roles after editing `agents/*.md`:

# Regenerate Codex native roles from canonical agent markdown
```bash
./ai/scripts/generate-codex-agents.py
```

### Plugin Structure
## Layout

The `ai/` directory is the plugin root:

```
```text
ai/
.claude-plugin/
plugin.json Plugin manifest
agents/ Subagent definitions
scripts/ Runtime adapter generators
skills/ Workflow skills and domain expertise
hooks/ Event handlers
AGENTS.md Shared instructions
mcp.json MCP server definitions
claude-settings.json Default settings
statusline.sh Custom statusline
```

> For the author's personal dotfiles setup, DotBot symlinks this directory to `~/.claude/`. Run `./install` from the repo root.

---

## Architecture

Workflows orchestrate multi-step processes by spawning agents, which may load
domain skills for expertise. Claude reads `agents/*.md` directly. Codex uses
generated native roles under `~/.codex/agents/stephendolan/`; regenerate them
with `./ai/scripts/generate-codex-agents.py` after editing agent markdown.

```mermaid
flowchart LR
subgraph Workflows
cm["/commit"]
cpr["/create-pr"]
sh["/ship"]
ri["/refine-implementation"]
ea["/examine-architecture"]
ica["/improve-codebase-architecture"]
apr["/address-pr-review"]
rd["/review-dependabot"]
int["/interview"]
gm["/grill-me"]
end

subgraph Agents
ce["code-explorer"]
ca["code-architect"]
cr["code-reviewer"]
cf["code-refiner"]
ar["architecture-reviewer"]
pr["plan-refiner"]
pcr["pr-comment-reviewer"]
dr["design-refiner"]
docr["documentation-refiner"]
sk["skeptic"]
end

subgraph Domain Skills
fdd["frontend-design"]
wcs["writing-claude-skills"]
wcp["writing-claude-prompts"]
wdoc["writing-documentation"]
mt["mom-test"]
end

sh --> ce & ca & cr & sk
ri --> cf
ea --> ar & pr
ica --> ar & pr
apr --> pcr
rd --> cr

dr -.-> fdd

classDef workflow fill:#4a5568,stroke:#2d3748,color:#fff
classDef agent fill:#3182ce,stroke:#2c5282,color:#fff
classDef skill fill:#38a169,stroke:#276749,color:#fff

class cm,cpr,sh,ri,ea,ica,apr,rd,int,gm workflow
class ce,ca,cr,cf,ar,pr,pcr,dr,docr,sk agent
class fdd,wcs,wcp,wdoc,mt skill
├── .claude-plugin/plugin.json
├── agents/ # Canonical runtime-neutral roles
├── skills/ # Personal workflows and domain knowledge
├── scripts/ # Runtime adapters
├── hooks/ # Event handlers
├── AGENTS.md # Shared operating preferences
├── claude-settings.json
└── mcp.json
```

**Legend**: Workflows (gray) spawn Agents (blue) which load Domain Skills (green)
## Skills

---
User-invoked skills spend no model context until Stephen calls them:

## Workflows
| Skill | Purpose |
| --- | --- |
| `refine-implementation` | Fresh-eyes implementation refinement |
| `thermonuclear-review` | Strict structural maintainability review |
| `improve-codebase-architecture` | Deep-module architecture exploration |
| `grill-me` | Decision-tree interrogation of a plan |
| `mom-test` | Customer-discovery question and evidence review |
| `drama-triangle` | Communication and agency analysis |

| Workflow | Purpose |
| --------------------------------- | -------------------------------------------------- |
| `/commit` | Commit with conventional message (why > what) |
| `/create-pr` | Create PR with concise description |
| `/ship` | Autonomous end-to-end feature development |
| `/refine-implementation` | Multi-pass quality review before committing |
| `/examine-architecture` | Evaluate codebase for structural problems |
| `/improve-codebase-architecture` | Find deepening opportunities informed by ADRs |
| `/address-pr-review` | Resolve unresolved PR review comments |
| `/review-dependabot` | Analyze and merge Dependabot PRs with safety check |
| `/interview` | Interview user about a plan before implementation |
| `/grill-me` | Relentless decision-tree interrogation of a plan |
Model-invoked skills route natural-language requests into local tools or data:

### Execution Flow Examples

```
/ship "Add user authentication"
Discovery -> Exploration (code-explorer) -> Architecture (code-architect)
-> Implementation -> Review (code-reviewer) -> Summary

/refine-implementation
code-refiner: simplicity -> configuration compliance -> conventions
-> Reconcile changes, iterate if needed

/examine-architecture
architecture-reviewer (parallel, one per surface)
-> Consolidate findings -> plan-refiner validates fixes
```

---
| Skill | Trigger |
| --- | --- |
| `writing` | Email, messages, Linear, support replies, and other human-facing prose |
| `notes-knowledge-base` | Stephen's Obsidian knowledge base and Tuple-call synthesis |
| `say` | Requested spoken output through ElevenLabs |

## Agents

| Agent | Purpose |
| ------------------------- | -------------------------------------------------- |
| **code-explorer** | Trace execution paths, map dependencies |
| **code-architect** | Design feature architectures |
| **code-reviewer** | Review for bugs, security, conventions |
| **code-refiner** | Simplify complexity, improve maintainability |
| **architecture-reviewer** | Evaluate brittleness, complexity, coupling |
| **plan-refiner** | Validate plans, suggest simpler approaches |
| **pr-comment-reviewer** | Evaluate PR comments for actionability |
| **design-refiner** | Iteratively refine frontend designs |
| **documentation-refiner** | Maintain Markdown files and developer docs |
| **skeptic** | Challenge conclusions before they reach the user |

---

## Domain Skills

Domain skills provide expertise activated automatically by context.

| Skill | Trigger |
| -------------------------- | ----------------------------------- |
| **frontend-design** | Building web interfaces |
| **writing-documentation** | Updating docs |
| **writing-claude-skills** | Creating Claude Code skills |
| **writing-claude-prompts** | Writing prompts for Claude |
| **mom-test** | Customer-discovery interview design |
| **drama-triangle** | Communication and conflict analysis |
| **task-management** | GTD workflow with OmniFocus |
| **notes-knowledge-base** | Maintain Stephen's Obsidian notes knowledge base |

---
Claude reads `agents/*.md` directly. Codex uses generated TOML roles under
`~/.codex/agents/stephendolan/`. Keep the markdown definitions canonical and
regenerate runtime copies instead of maintaining both by hand.

## MCP Servers

The `mcp.json` file defines MCP server connections:

| Server | Purpose |
| --------------- | ----------------------------- |
| **betterstack** | Logging and uptime monitoring |
| **chartmogul** | Revenue analytics |
| **helpscout** | Customer support |
| **omnifocus** | Task management |
| **ynab** | Budget tracking |

Run `./generate-mcp.sh` to sync servers to Claude CLI and Codex CLI.
`mcp.json` defines personal server connections. Run `./generate-mcp.sh` to sync
managed entries to Claude and Codex while preserving client-specific servers.
Loading
Loading