chore: update opencode workflow and local config
This commit is contained in:
alex wiesner
@@ -4,6 +4,37 @@ type: note
|
||||
permalink: opencode-config/agents
|
||||
---
|
||||
|
||||
## MCP Code-Indexing Tooling
|
||||
|
||||
This repo configures two MCP servers for structural code analysis, registered in `opencode.jsonc`:
|
||||
|
||||
| Server | Purpose | Runtime |
|
||||
|---|---|---|
|
||||
| `ast-grep` | Structural pattern search (AST-level grep) | `uvx` (Python/uv) |
|
||||
| `codebase-memory` | Relationship mapping, dependency graphs, blast-radius analysis | `codebase-memory-mcp` binary |
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- `uvx` available on `PATH` (for `ast-grep`)
|
||||
- `codebase-memory-mcp` binary installed and on `PATH`
|
||||
|
||||
### Intended usage layering
|
||||
|
||||
When analyzing code, prefer tools in this order to minimize overhead:
|
||||
|
||||
1. **`ast-grep` first** — structural pattern matching; fastest and most targeted
|
||||
2. **`codebase-memory` next** — relationship/blast-radius queries when structure alone is insufficient
|
||||
|
||||
### Role allocation (summary)
|
||||
|
||||
Per-agent tooling scopes are defined in each agent's guidance file under `agents/`. The high-level allocation:
|
||||
|
||||
- **coder**: `ast-grep` only for targeted implementation discovery; avoid `codebase-memory` unless explicitly needed
|
||||
- **explorer / researcher / sme / reviewer / tester**: `ast-grep` + `codebase-memory`
|
||||
- **critic / designer / librarian**: no code-indexing tooling guidance (use standard tools)
|
||||
|
||||
Detailed per-agent behavioral guidance lives in `agents/*.md` files and is not duplicated here.
|
||||
|
||||
## Memory System (Single: basic-memory)
|
||||
|
||||
Memory uses one persistent system: **basic-memory**.
|
||||
@@ -226,6 +257,12 @@ All agents except `lead`, `coder`, and `librarian` are code/source read-only. Ag
|
||||
- **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, and subagent delegations alike.
|
||||
- Before issuing a sequence of calls, ask: *"Does call B require the result of call A?"* If not, send them together.
|
||||
|
||||
## Skill Loading Policy
|
||||
|
||||
- Relevant skills are **not optional**. When a task matches a skill's trigger conditions, the lead must load that skill proactively before proceeding with ad hoc execution.
|
||||
- Keep skill usage operational: use skills to drive planning, decomposition, debugging, verification, and workflow enforcement instead of relying on generic reminders.
|
||||
- `AGENTS.md` defines this as policy; concrete skill trigger rules and enforcement behavior belong in `agents/lead.md`.
|
||||
|
||||
## Human Checkpoint Triggers
|
||||
|
||||
When implementing features, the Lead must stop and request explicit user approval before dispatching coder work in these situations:
|
||||
@@ -313,3 +350,69 @@ Before implementing a feature, the lead must verify its understanding of what th
|
||||
When in doubt, ask. A 30-second clarification prevents hours of rework on a fundamentally misunderstood feature.
|
||||
|
||||
This complements the Clarification Rule above — that rule covers *ambiguous requirements*; this rule covers *requirements that seem clear but may be misunderstood*. The test: "If I'm wrong about what this means, would I build something completely different?" If yes, verify.
|
||||
|
||||
## Proactive Bug Search
|
||||
|
||||
Do not limit quality work to the requested diff. The Lead should actively search for likely related defects before and after implementation.
|
||||
|
||||
### Minimum proactive bug-hunt pass
|
||||
|
||||
For any non-trivial feature or bug fix, inspect nearby risk surfaces in addition to the primary edit point:
|
||||
|
||||
- sibling components/handlers in the same feature area
|
||||
- duplicated or copy-pasted logic paths
|
||||
- recent churn hotspots and TODO/FIXME comments
|
||||
- adjacent validation, error handling, empty-state, and permission logic
|
||||
- parallel codepaths that should stay behaviorally consistent
|
||||
|
||||
This pass is not open-ended archaeology; it is a focused search for bugs that are likely to be coupled to the requested work.
|
||||
|
||||
### Discovery and review expectations
|
||||
|
||||
- During DISCOVER, include a short "likely bug surfaces" list in the findings when the task is non-trivial.
|
||||
- During EXECUTE, require reviewer and tester prompts to check for **related regressions and likely adjacent bugs**, not just direct spec compliance.
|
||||
- If proactive bug hunting finds unrelated non-blocking issues, record them in project memory or a backlog note rather than silently folding them into the current task.
|
||||
- If a discovered bug is blocking correctness of the current task, treat it as in-scope and explicitly add it to the plan.
|
||||
|
||||
### Bug-fix workflow
|
||||
|
||||
- Prefer reproduction-first debugging: capture the failing scenario, failing test, or concrete bug path before fixing when feasible.
|
||||
- After the fix, re-run the same scenario as the primary verification step.
|
||||
- For bug fixes without an automated regression test, document the exact manual reproduction and re-verification path.
|
||||
|
||||
## Planning Rigor
|
||||
|
||||
Planning should be detailed enough to reduce rework, not just to describe intent.
|
||||
|
||||
### Plan minimums
|
||||
|
||||
Every non-trivial plan must include, per task or feature:
|
||||
|
||||
- the exact user-visible outcome
|
||||
- explicit acceptance criteria
|
||||
- edge cases and error cases
|
||||
- non-goals / what is intentionally out of scope
|
||||
- verification method
|
||||
- impacted files, systems, or integration surfaces
|
||||
- likely breakage or regression surfaces
|
||||
|
||||
### Required pre-mortem
|
||||
|
||||
Before EXECUTE, add a short pre-mortem section to the plan for non-trivial work:
|
||||
|
||||
- what is most likely to fail
|
||||
- which assumption is most fragile
|
||||
- what would force a redesign or user checkpoint
|
||||
- what regression is easiest to miss
|
||||
|
||||
The goal is to surface rework risks early, before coder dispatch.
|
||||
|
||||
### Retry learning loop
|
||||
|
||||
When review or testing fails and a retry is needed, update the plan with a brief note covering:
|
||||
|
||||
- what was misunderstood or missed
|
||||
- what new constraint was discovered
|
||||
- what changed in the execution approach
|
||||
|
||||
Do not resend the same plan unchanged after a failed cycle unless the failure was purely mechanical.
|
||||
|
||||
@@ -47,6 +47,11 @@ Scope rejection (hard rule):
|
||||
10. **Discover local conventions first.** Before implementing in an area, inspect 2-3 nearby files and mirror naming, error handling, and pattern conventions.
|
||||
11. **Memory recording discipline.** Record only structural discoveries (new module/pattern/contract) or implementation decisions in relevant basic-memory project notes, link related sections with markdown cross-references, and never record ceremony entries like "started/completed implementation".
|
||||
|
||||
Tooling guidance (targeted):
|
||||
|
||||
- Prefer `ast-grep` for structural code search, scoped pattern matching, and safe pre-edit discovery.
|
||||
- Do not use `codebase-memory` for routine implementation tasks unless the delegation explicitly requires graph/blast-radius analysis.
|
||||
|
||||
Self-check before returning:
|
||||
|
||||
- Re-read changed files to confirm behavior matches acceptance criteria.
|
||||
@@ -79,4 +84,4 @@ RISKS: <anything reviewer/tester should pay special attention to>
|
||||
Status semantics:
|
||||
|
||||
- `BLOCKED`: external blocker prevents completion.
|
||||
- `PARTIAL`: subset completed; report what remains.
|
||||
- `PARTIAL`: subset completed; report what remains.
|
||||
|
||||
@@ -31,6 +31,11 @@ Operating rules:
|
||||
7. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
|
||||
8. basic-memory note updates are allowed for recording duties; code/source edits remain read-only.
|
||||
|
||||
Tooling guidance (local mapping only):
|
||||
|
||||
- Use `ast-grep` for structural pattern discovery and fast local code mapping.
|
||||
- Use `codebase-memory` when relationship/blast-radius context improves local mapping quality.
|
||||
|
||||
Required output contract (required):
|
||||
|
||||
```text
|
||||
@@ -48,5 +53,9 @@ DEPENDENCIES:
|
||||
|
||||
RISKS:
|
||||
- <risk description>
|
||||
|
||||
LIKELY_BUG_SURFACES:
|
||||
- <nearby file/component/path>: <coupled defect or consistency risk>
|
||||
```
|
||||
|
||||
- For non-trivial work, `LIKELY_BUG_SURFACES` is required and must identify nearby files/components/paths that may share coupled defects or consistency risks.
|
||||
|
||||
@@ -37,6 +37,17 @@ You are the Lead agent, the primary orchestrator.
|
||||
- Require subagents to update that plan note with findings/verdicts relevant to their task.
|
||||
- If no plan note exists yet and work is non-trivial, create one during PLAN before delegating.
|
||||
|
||||
## MCP Code-Indexing Orchestration
|
||||
|
||||
- Use this layering when delegating code-discovery work:
|
||||
1. `ast-grep` first for fast structural search/pattern matching.
|
||||
2. `codebase-memory` next for cross-file relationships, blast radius, and graph-style context.
|
||||
- Delegate by role value (do not broadcast every tool to every agent):
|
||||
- `coder`: `ast-grep` only for targeted implementation discovery; avoid `codebase-memory` unless the task explicitly needs graph/blast-radius analysis.
|
||||
- `explorer`: `ast-grep` + `codebase-memory`.
|
||||
- `researcher` / `sme`: `ast-grep` + `codebase-memory` when technical depth justifies it.
|
||||
- `reviewer` / `tester`: `ast-grep` + `codebase-memory`.
|
||||
|
||||
## Delegation Trust
|
||||
|
||||
- **Do not re-do subagent work.** When a subagent (explorer, researcher, etc.) returns findings on a topic, use those findings directly. Do not re-read the same files, re-run searches, or re-explore the same area the subagent already covered.
|
||||
@@ -63,6 +74,56 @@ Before dispatching coders or testers to a project with infrastructure dependenci
|
||||
- **Anti-pattern:** Dispatching 5 coder/tester attempts that all fail with the same `connection refused` or `permission denied` error without ever diagnosing why.
|
||||
- **Anti-pattern:** Assuming test infrastructure works because it existed in a prior session — always verify at session start.
|
||||
|
||||
## Skill Trigger Enforcement (Mandatory)
|
||||
|
||||
- Relevant skills are not optional. Once a matching trigger is recognized, load the skill **before** continuing ad hoc orchestration.
|
||||
- Do not rely on generic reminders when a concrete skill already covers the workflow.
|
||||
- Skill loading is a control point: if a trigger matches and no skill is loaded, pause and load it.
|
||||
|
||||
### Mandatory `writing-plans` threshold (non-trivial work)
|
||||
|
||||
Load `writing-plans` before finalizing PLAN when **any** of the following is true:
|
||||
|
||||
- likely touches more than 2 files
|
||||
- more than one independently meaningful task
|
||||
- user-visible behavior changes
|
||||
- cross-system integration or data flow changes
|
||||
- verification requires more than one command or more than one validation mode
|
||||
|
||||
### Skill → trigger mapping
|
||||
|
||||
- `writing-plans`: any non-trivial work per threshold above.
|
||||
- `work-decomposition`: request includes 3+ features or spans independent domains/risk profiles.
|
||||
- `systematic-debugging`: first real bug investigation, unexpected failure, flaky behavior, or repeated failing verification.
|
||||
- `verification-before-completion`: before declaring success on any non-trivial change set.
|
||||
- `test-driven-development`: bug fixes and net-new features when tests are expected to exist or be added; if not used, record an explicit reason.
|
||||
- `requesting-code-review`: before reviewer dispatch for non-trivial feature work so review scope/checks are explicit.
|
||||
- `git-workflow`: before git operations beyond basic status/diff inspection, especially branch/worktree/commit/PR actions.
|
||||
- `doc-coverage`: when a completed change set may require README/docs/AGENTS/basic-memory updates.
|
||||
- `dispatching-parallel-agents`: when 2+ independent subagent tasks can run concurrently.
|
||||
- `creating-agents`: when adding or modifying agent definitions.
|
||||
- `creating-skills`: when adding or modifying skill definitions.
|
||||
- `executing-plans` / `subagent-driven-development`: when executing an approved stored plan; select the one matching intended execution style.
|
||||
|
||||
### Mandatory SME consultation triggers
|
||||
|
||||
Consult `sme` when any condition below is true **and no fresh validated guidance already exists**:
|
||||
|
||||
- 2+ plausible technical approaches with materially different tradeoffs.
|
||||
- Unfamiliar framework/API/library/protocol behavior is central to the change.
|
||||
- Auth/security/permissions/secrets/trust boundaries are involved.
|
||||
- Data model/migration/persistence semantics are involved.
|
||||
- Performance/concurrency/caching/consistency questions are involved.
|
||||
- Cross-system integration has ambiguous contracts or failure behavior.
|
||||
- The same task has already failed 2 review/test/coder cycles.
|
||||
- Reviewer rejected the approach or repeated the same class of concern twice.
|
||||
- Lead has low confidence in a technical decision even when requirements are clear.
|
||||
|
||||
### Planner role clarification
|
||||
|
||||
- A dedicated planner subagent is not required by default.
|
||||
- The Lead enforces planning rigor directly through `writing-plans`; only revisit planner specialization if a real capability gap remains after using the skill.
|
||||
|
||||
## Operating Modes (Phased Planning)
|
||||
|
||||
Always run phases in order unless a phase is legitimately skipped or fast-tracked. At every transition:
|
||||
|
||||
@@ -29,6 +29,12 @@ Operating rules:
|
||||
9. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
|
||||
10. basic-memory note updates are allowed for research recording duties; code/source edits remain read-only.
|
||||
|
||||
Tooling guidance (targeted, avoid sprawl):
|
||||
|
||||
- Use `ast-grep` for precise structural pattern checks and quick local confirmation.
|
||||
- Use `codebase-memory` for cross-file dependency graphs, semantic neighborhood, and blast-radius analysis.
|
||||
- Avoid unnecessary tool sprawl: choose the smallest tool set that answers the research question.
|
||||
|
||||
Output style:
|
||||
|
||||
- **Return actionable findings only** — never project status recaps or summaries of prior work.
|
||||
@@ -36,4 +42,4 @@ Output style:
|
||||
- Provide supporting details with references.
|
||||
- List assumptions, tradeoffs, and recommended path.
|
||||
- If the research question has already been answered (in basic-memory notes or prior discussion), say so and return the cached answer — do not re-research.
|
||||
- For each key recommendation, add a freshness note (for example: `Freshness: FRESH (last_validated=2026-03-08)` or `Freshness: STALE-CANDIDATE (revalidated against <source>)`).
|
||||
- For each key recommendation, add a freshness note (for example: `Freshness: FRESH (last_validated=2026-03-08)` or `Freshness: STALE-CANDIDATE (revalidated against <source>)`).
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
description: Read-only code review agent for quality, risk, and maintainability
|
||||
mode: subagent
|
||||
model: github-copilot/claude-opus-4.6
|
||||
model: github-copilot/gpt-5.4
|
||||
temperature: 0.3
|
||||
permission:
|
||||
edit: allow
|
||||
@@ -35,6 +35,13 @@ Operating rules:
|
||||
6. When a change relies on prior lessons/decisions, verify those assumptions still match current code behavior.
|
||||
7. Flag stale-assumption risk as `WARNING` or `CRITICAL` based on impact.
|
||||
8. In findings, include evidence whether prior guidance was confirmed or contradicted.
|
||||
9. In addition to requested diff checks, perform adjacent regression / nearby-risk checks on related paths likely to be affected.
|
||||
|
||||
Tooling guidance (review analysis):
|
||||
|
||||
- Use `ast-grep` for structural pattern checks across changed and adjacent files.
|
||||
- Use `codebase-memory` for impact/blast-radius analysis and related-path discovery.
|
||||
- Keep review tooling read-only and evidence-driven.
|
||||
|
||||
Two-lens review model:
|
||||
|
||||
@@ -138,6 +145,8 @@ SUGGESTIONS:
|
||||
- <optional improvement>
|
||||
NEXT: <what coder should fix, if applicable>
|
||||
FRESHNESS_NOTES: <optional concise note on prior lessons: confirmed|stale|contradicted>
|
||||
RELATED_REGRESSION_CHECKS:
|
||||
- <adjacent path/component reviewed>: <issues found|no issues found>
|
||||
```
|
||||
|
||||
Output quality requirements:
|
||||
@@ -151,4 +160,4 @@ Memory recording duty:
|
||||
- After issuing a verdict, record it in the per-repo basic-memory project under `gates/` or `decisions/` as appropriate.
|
||||
- Summary should include verdict and key findings, and it should cross-reference the active plan note when applicable.
|
||||
- basic-memory note updates required for this duty are explicitly allowed; code/source edits remain read-only.
|
||||
- Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
|
||||
- Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
|
||||
|
||||
@@ -22,6 +22,7 @@ Tool restrictions:
|
||||
|
||||
- Allowed: `read`, `glob`, `grep`, `webfetch`, `websearch`, `codesearch`, and basic-memory MCP tools (`write_note`, `read_note`, `search_notes`, `build_context`).
|
||||
- Disallowed: implementation source file edits and shell commands.
|
||||
- Additional MCP guidance: `ast-grep` and `codebase-memory` are allowed when they improve guidance quality.
|
||||
|
||||
Guidance caching rule (critical):
|
||||
|
||||
@@ -54,6 +55,14 @@ Workflow:
|
||||
6. Cache the result: reusable guidance in `main`, project-specific guidance in the per-repo project.
|
||||
7. Return structured guidance.
|
||||
|
||||
Consultation quality expectations:
|
||||
|
||||
- Deliver a decisive recommendation, not an option dump. If options are presented, clearly state the recommended path and why.
|
||||
- Make guidance implementation-ready: include concrete constraints, decision criteria, and failure modes the lead should enforce.
|
||||
- Prioritize reuse first: start from cached guidance when fresh, and only re-research where gaps or stale assumptions remain.
|
||||
- Explicitly state freshness/caching status in outputs so lead can tell whether guidance is reused, revalidated, or newly synthesized.
|
||||
- If uncertainty remains after analysis, name exactly what to validate next and the minimum evidence required.
|
||||
|
||||
Output format:
|
||||
|
||||
```text
|
||||
@@ -62,4 +71,7 @@ GUIDANCE: <detailed answer>
|
||||
TRADEOFFS: <key tradeoffs if applicable>
|
||||
REFERENCES: <sources if externally researched>
|
||||
CACHED_AS: <basic-memory note title/path>
|
||||
```
|
||||
FRESHNESS: <reused-fresh|revalidated|new|stale-needs-validation>
|
||||
RECOMMENDATION: <single actionable recommendation>
|
||||
RATIONALE: <why this recommendation is preferred>
|
||||
```
|
||||
|
||||
@@ -40,6 +40,13 @@ Operating rules:
|
||||
6. **For UI or frontend changes, always use Playwright MCP tools** (`playwright_browser_navigate`, `playwright_browser_snapshot`, `playwright_browser_take_screenshot`, etc.) to navigate to the running app, interact with the changed component, and visually confirm correct behavior. A code-only review is not sufficient for UI changes.
|
||||
7. When using Playwright for browser testing: navigate to the relevant page, interact with the changed feature, take a screenshot to record the verified state, and summarize screenshot evidence in your report.
|
||||
8. **Clean up test artifacts.** After testing, delete any generated files (screenshots, temp files, logs). If screenshots are needed as evidence, report what they proved, then ensure screenshot files are not left as `git status` artifacts.
|
||||
9. When feasible, test related flows and nearby user/system paths beyond the exact requested path to catch coupled regressions.
|
||||
|
||||
Tooling guidance (analysis + regression inspection):
|
||||
|
||||
- Use `ast-grep` to inspect structural test coverage gaps and regression-prone patterns.
|
||||
- Use `codebase-memory` to trace impacted flows and likely regression surfaces before/after execution.
|
||||
- Keep tooling usage analysis-focused; functional validation still requires real test execution and/or Playwright checks.
|
||||
|
||||
Two-pass testing protocol:
|
||||
|
||||
@@ -92,6 +99,8 @@ LESSON_CHECKS:
|
||||
FAILURES:
|
||||
- <test name>: <root cause>
|
||||
NEXT: <what coder needs to fix, if STATUS != PASS>
|
||||
RELATED_FLOW_CHECKS:
|
||||
- <nearby flow exercised>: <result>
|
||||
```
|
||||
|
||||
Memory recording duty:
|
||||
@@ -105,4 +114,4 @@ Infrastructure unavailability:
|
||||
|
||||
- **If the test suite cannot run** (e.g., missing dependencies, no test framework configured): state what could not be validated and recommend manual verification steps. Never claim testing is "passed" when no tests were actually executed.
|
||||
- **If the dev server cannot be started** (e.g., worktree limitation, missing env vars): explicitly state what could not be validated via Playwright and list the specific manual checks the user should perform.
|
||||
- **Never perform "static source analysis" as a substitute for real testing.** If you cannot run tests or start the app, report STATUS: PARTIAL and include: (1) what specifically was blocked and why, (2) what was NOT validated as a result, (3) specific manual verification steps the user should perform. The lead agent treats PARTIAL as a blocker — incomplete validation is never silently accepted.
|
||||
- **Never perform "static source analysis" as a substitute for real testing.** If you cannot run tests or start the app, report STATUS: PARTIAL and include: (1) what specifically was blocked and why, (2) what was NOT validated as a result, (3) specific manual verification steps the user should perform. The lead agent treats PARTIAL as a blocker — incomplete validation is never silently accepted.
|
||||
|
||||
@@ -8,6 +8,9 @@
|
||||
"enabled": true,
|
||||
"protectedTools": [],
|
||||
},
|
||||
"experimental": {
|
||||
"allowSubAgents": true,
|
||||
}
|
||||
"manualMode": {
|
||||
"enabled": false,
|
||||
"automaticStrategies": true,
|
||||
@@ -17,25 +20,6 @@
|
||||
"turns": 4,
|
||||
},
|
||||
"protectedFilePatterns": [],
|
||||
"tools": {
|
||||
"settings": {
|
||||
"nudgeEnabled": true,
|
||||
"nudgeFrequency": 10,
|
||||
"contextLimit": 80%,
|
||||
"protectedTools": [],
|
||||
},
|
||||
"distill": {
|
||||
"permission": "allow",
|
||||
"showDistillation": false,
|
||||
},
|
||||
"compress": {
|
||||
"permission": "deny",
|
||||
"showCompression": false,
|
||||
},
|
||||
"prune": {
|
||||
"permission": "allow",
|
||||
},
|
||||
},
|
||||
"strategies": {
|
||||
"deduplication": {
|
||||
"enabled": true,
|
||||
@@ -50,4 +34,8 @@
|
||||
"protectedTools": [],
|
||||
},
|
||||
},
|
||||
"compress": {
|
||||
"maxContextLimit": "80%",
|
||||
"minContextLimit": "50%"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
"playwright": {
|
||||
"type": "local",
|
||||
"command": [
|
||||
"npx",
|
||||
"bunx",
|
||||
"@playwright/mcp@latest",
|
||||
"--headless",
|
||||
"--browser",
|
||||
@@ -40,13 +40,24 @@
|
||||
"enabled": true
|
||||
},
|
||||
"basic-memory": {
|
||||
"type": "local",
|
||||
"command": ["uvx", "basic-memory", "mcp"],
|
||||
"enabled": true
|
||||
},
|
||||
"ast-grep": {
|
||||
"type": "local",
|
||||
"command": [
|
||||
"uvx",
|
||||
"basic-memory",
|
||||
"mcp"
|
||||
"--from",
|
||||
"git+https://github.com/ast-grep/ast-grep-mcp",
|
||||
"ast-grep-server"
|
||||
],
|
||||
"enabled": true
|
||||
},
|
||||
"codebase-memory": {
|
||||
"type": "local",
|
||||
"command": ["codebase-memory-mcp", "mcp"],
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
66
.config/opencode/skills/creating-agents/SKILL.md
Normal file
66
.config/opencode/skills/creating-agents/SKILL.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: creating-agents
|
||||
description: Create or update opencode agents in this repository, including dispatch permissions and roster alignment requirements
|
||||
permalink: opencode-config/skills/creating-agents/skill
|
||||
---
|
||||
|
||||
# Creating Agents
|
||||
|
||||
Use this skill when you need to add or revise an agent definition in this repo.
|
||||
|
||||
## Agents vs Skills
|
||||
|
||||
- **Agents** define runtime behavior and permissions in `agents/*.md`.
|
||||
- **Skills** are reusable instruction modules under `skills/*/SKILL.md`.
|
||||
- Do not treat agent creation as skill creation; each has different files and checks.
|
||||
|
||||
## Source of Truth
|
||||
|
||||
1. Agent definition file: `agents/<agent-name>.md`
|
||||
2. Dispatch permissions for new dispatchable agents: `agents/lead.md`
|
||||
- `permission.task.<agent-name>: allow` must be present for lead dispatch.
|
||||
3. Human-readable roster: `AGENTS.md`
|
||||
- Keep the roster table synchronized with actual agent files.
|
||||
4. Runtime overrides: `opencode.jsonc`
|
||||
- May override/disable agent behavior.
|
||||
- Does **not** register a new agent.
|
||||
|
||||
## Agent File Conventions
|
||||
|
||||
For `agents/<agent-name>.md`:
|
||||
|
||||
- Use frontmatter first, then concise role instructions.
|
||||
- Keep tone imperative and operational.
|
||||
- Include only permissions and behavior needed for the role.
|
||||
- Align with existing files such as `agents/lead.md` and `agents/coder.md`.
|
||||
|
||||
Typical frontmatter fields in this repo include:
|
||||
|
||||
- `description`
|
||||
- `mode`
|
||||
- `model` (for subagents where needed)
|
||||
- `temperature`
|
||||
- `permission`
|
||||
- `permalink`
|
||||
|
||||
Mirror nearby agent files instead of inventing new metadata patterns.
|
||||
Note: `agents/lead.md` is the only `mode: primary` agent. New agents should normally mirror a comparable subagent and use `mode: subagent` with an explicit `model`.
|
||||
|
||||
## Practical Workflow (Create or Update)
|
||||
|
||||
1. Inspect `agents/lead.md` and at least one similar `agents/*.md` file.
|
||||
2. Create or edit `agents/<agent-name>.md` with matching local structure.
|
||||
3. If the agent must be dispatchable, add `permission.task.<agent-name>: allow` in `agents/lead.md`.
|
||||
4. Update `AGENTS.md` roster entry to match the new/updated agent.
|
||||
5. Review `opencode.jsonc` for conflicting overrides/disable flags.
|
||||
|
||||
## Manual Verification Checklist (No Validation Script)
|
||||
|
||||
Run this checklist before claiming completion:
|
||||
|
||||
- [ ] `agents/<agent-name>.md` exists and frontmatter is valid/consistent with peers.
|
||||
- [ ] Agent instructions clearly define role, scope, and constraints.
|
||||
- [ ] `agents/lead.md` includes `permission.task.<agent-name>: allow` if dispatch is required.
|
||||
- [ ] `AGENTS.md` roster row exists and matches agent name/role/model.
|
||||
- [ ] `opencode.jsonc` does not unintentionally disable or override the new agent.
|
||||
- [ ] Terminology stays consistent: agents in `agents/*.md`, skills in `skills/*/SKILL.md`.
|
||||
64
.config/opencode/skills/creating-skills/SKILL.md
Normal file
64
.config/opencode/skills/creating-skills/SKILL.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: creating-skills
|
||||
description: Create or update opencode skills in this repository using the required SKILL.md format and concise, trigger-focused guidance
|
||||
permalink: opencode-config/skills/creating-skills/skill
|
||||
---
|
||||
|
||||
# Creating Skills
|
||||
|
||||
Use this skill when you need to add or revise an opencode skill under `skills/`.
|
||||
|
||||
## Skills vs OpenAI/Codex Source Model
|
||||
|
||||
- Treat this repo as **opencode-native**.
|
||||
- Do **not** use OpenAI/Codex-specific artifacts such as `agents/openai.yaml`, `init_skill.py`, `quick_validate.py`, or `scripts/references/assets` conventions from the old source model.
|
||||
- A skill is discovered from `skills/*/SKILL.md` only.
|
||||
|
||||
## Required Structure
|
||||
|
||||
1. Create a folder at `skills/<skill-name>/`.
|
||||
2. Add `skills/<skill-name>/SKILL.md`.
|
||||
3. Keep `<skill-name>` equal to frontmatter `name`.
|
||||
|
||||
Frontmatter must contain only:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-name>
|
||||
description: <what it does and when to load>
|
||||
permalink: opencode-config/skills/<skill-name>/skill
|
||||
---
|
||||
```
|
||||
|
||||
## Naming Rules
|
||||
|
||||
- Use lowercase kebab-case.
|
||||
- Keep names short and action-oriented.
|
||||
- Match folder name and `name` exactly.
|
||||
|
||||
## Body Writing Rules
|
||||
|
||||
- Write concise, imperative instructions.
|
||||
- Lead with when to load and the core workflow.
|
||||
- Prefer short checklists over long prose.
|
||||
- Include only repo-relevant guidance.
|
||||
|
||||
## Companion Notes (`*.md` in skill folder)
|
||||
|
||||
Add companion markdown files only when detail would bloat `SKILL.md` (examples, deep procedures, edge-case references).
|
||||
|
||||
- Keep `SKILL.md` as the operational entrypoint.
|
||||
- Link companion files directly from `SKILL.md` with clear “when to read” guidance.
|
||||
- Do not create extra docs by default.
|
||||
|
||||
## Practical Workflow (Create or Update)
|
||||
|
||||
1. Inspect 2–3 nearby skills for local style and brevity.
|
||||
2. Pick/update `<skill-name>` and folder path under `skills/`.
|
||||
3. Write or revise `SKILL.md` frontmatter (`name`, `description`, `permalink` only).
|
||||
4. Draft concise body sections: purpose, load conditions, workflow, red flags/checks.
|
||||
5. Add minimal companion `.md` files only if needed; link them from `SKILL.md`.
|
||||
6. Verify discovery path and naming consistency:
|
||||
- file exists at `skills/<name>/SKILL.md`
|
||||
- folder name == frontmatter `name`
|
||||
- no OpenAI/Codex-only artifacts introduced
|
||||
Reference in New Issue
Block a user