Skip to content

refactor(config): restructure opencode config and clean up obsolete files #2

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

Open
Jonathan0823 wants to merge 11 commits into
base: main
Choose a base branch
from
Open

refactor(config): restructure opencode config and clean up obsolete files #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
76563ec
refactor(config): restructure opencode config and clean up obsolete f…
Jonathan0823 May 22, 2026
cf5b6dd
docs(commands): refactor commit and pr to plan-only workflows
Jonathan0823 May 22, 2026
3aae321
docs(commands): add STOP HERE enforcement reminders to commit and pr …
Jonathan0823 May 22, 2026
e2272f8
docs(commands): improve pr command documentation with skill template …
Jonathan0823 May 22, 2026
a912913
fix(commands): set subtask false for commit and pr commands
Jonathan0823 May 22, 2026
ac606ae
refactor(commit): rewrite /commit as multi-draft SRP-first workflow
Jonathan0823 May 22, 2026
36351e6
docs: update /commit references to multi-draft SRP workflow
Jonathan0823 May 22, 2026
ef8413f
feat(subagent): update prompts
Jonathan0823 May 23, 2026
70600a6
feat(context): remove any oac related files from the context
Jonathan0823 May 23, 2026
81b3c57
feat(command): update spec command
Jonathan0823 May 23, 2026
b571ce7
feat(opencode): relax build agent permissions
Jonathan0823 May 23, 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
92 changes: 75 additions & 17 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This document outlines the standards and best practices for designing and implem
- Design interactions that prioritize user needs and preferences.
- Provide options for users to customize their experience with the AI agent.
- Always ask for questions when user intent is unclear or when multiple interpretations are possible.
- Offer to use specific subagents when appropriate: "Should I use @researcher to look into this?"
- Offer to use specific subagents when appropriate: "Should I use @ExternalScout to look up current docs?"

### 3. Reviewing & Debugging

Expand All @@ -29,42 +29,43 @@ This document outlines the standards and best practices for designing and implem

| Subagent | Purpose | When to Use |
|----------|---------|-------------|
| `@code-reviewer` | Code review | Reviewing code for quality, security, performance |
| `@researcher` | Research | Investigating libraries, patterns, solutions |
| `@refactorer` | Refactoring | Improving code structure safely |
| `@explainer` | Explanation | Understanding code, generating documentation |
| `@implementer` | Implementation | Building features end-to-end |
| `@CodeReviewer` | Code review | Reviewing code for quality, security, performance |
| `@ContextScout` | Internal context | Finding project standards and workflow context |
| `@ExternalScout` | External docs | Fetching current library/framework documentation |
| `@CoderAgent` | Bounded implementation | Executing specific subtasks after planning |
| `@TestEngineer` | Testing | Writing or expanding tests |
| `@DocWriter` | Documentation | Creating or updating docs |

### Usage Patterns

**For Research:**
```
User: "What's the best way to implement authentication in Go?"
→ Use @researcher
→ Use @ExternalScout for library docs, or @ContextScout for project conventions
```
Comment on lines 42 to 45
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifiers to fenced example blocks.

These fences currently trigger MD040 and can break markdown lint gates.

Suggested fix 
-```
+```text
 User: "What's the best way to implement authentication in Go?"
 → Use `@ExternalScout` for library docs, or `@ContextScout` for project conventions

Apply the same `text` fence language to the other example blocks in this section.
</details>


Also applies to: 48-51, 54-57, 60-63, 66-69

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>

[warning] 42-42: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @AGENTS.md around lines 42 - 45, The fenced example blocks containing lines
like User: "What's the best way to implement authentication in Go?" → Use @ExternalScoutfor library docs, or@ContextScout for project conventions
currently lack a language identifier and trip MD040; update each of these
triple-backtick fences to use text (i.e., add the `text` language after the opening ), and apply the same change to the other example blocks in this
section (the blocks showing the User/→ Use @ExternalScout/@ContextScout
examples) so all such fenced examples include the text language tag.


</details>

<!-- fingerprinting:phantom:poseidon:hawk -->

<!-- This is an auto-generated comment by CodeRabbit -->


**For Code Review:**
```
User: "Please review this code"
→ Use @code-reviewer
→ Use @CodeReviewer
```

**For Refactoring:**
```
User: "Refactor this to be more maintainable"
→ Use @refactorer
→ Use built-in build agent with the `refactoring-safely` skill, or @CoderAgent for a bounded subtask
```

**For Documentation:**
```
User: "Explain how this works and add docs"
→ Use @explainer
→ Use @DocWriter
```

**For Feature Implementation:**
```
User: "Build a user authentication system"
→ Use @implementer
→ Use built-in build agent; delegate bounded subtasks to @CoderAgent when useful
```

---
Expand All @@ -78,6 +79,8 @@ User: "Build a user authentication system"
- Use interfaces for testability
- Explicit error handling
- Small, focused functions
- Final handoff must run `gofmt` on changed Go files and `golangci-lint run ./...`
- If the lint command is unavailable, stop and report it before handoff

**Rust:**
- Follow `rust-patterns` skill
Expand All @@ -90,6 +93,15 @@ User: "Build a user authentication system"
- Strict TypeScript configuration
- Explicit types for public APIs
- Avoid `any` type
- Final handoff must run `npm run lint` for Next.js/TypeScript repos
- If the repo has TypeScript and no project typecheck script exists, run `npx tsc --noEmit`
- If the repo uses ESLint and TypeScript, both checks are required at handoff

**Next.js:**
- Treat Next.js as TypeScript rules plus framework-specific linting
- Final handoff must run `npm run lint`
- Final handoff must run `npx tsc --noEmit` when TypeScript is present
- If either command fails, stop and report before handoff

**Python:**
- Type hints for function signatures
Expand All @@ -112,17 +124,17 @@ User: "Build a user authentication system"

### Feature Development Process

1. **Research** → Use `@researcher` for investigation
1. **Research** → Use `@ContextScout` for internal patterns or `@ExternalScout` for current external docs
2. **Plan** → Define interfaces, break into tasks
3. **Implement** → Use `@implementer` or code directly
3. **Implement** → Use built-in build agent directly; delegate bounded subtasks to `@CoderAgent` when useful
4. **Test** → Unit, integration, manual tests
5. **Review** → Use `@code-reviewer`
6. **Document** → Use `@explainer`
5. **Review** → Use `@CodeReviewer`
6. **Document** → Use `@DocWriter`

### Bug Fixing Process

1. **Reproduce** → Create reliable test case
2. **Investigate** → Use `@researcher` if needed
2. **Investigate** → Use `@ContextScout` or `@ExternalScout` if needed
3. **Fix** → Minimal change, root cause
4. **Verify** → Tests pass
5. **Deploy** → Monitor for regression
Expand All @@ -133,7 +145,7 @@ User: "Build a user authentication system"
2. **Small Changes** → One change at a time
3. **Run Tests** → After every change
4. **Commit** → Frequent commits
5. **Review** → Use `@refactorer`
5. **Review** → Use `@CodeReviewer`

---

Expand All @@ -159,6 +171,18 @@ refactor(db): optimize queries
test(auth): add integration tests
```

### Commit Workflow

- Use `/commit` as a plan-first workflow, not a blind commit helper.
- `/commit` groups the diff by responsibility and produces **one numbered draft per group**.
- If the diff has a single responsibility, one draft is produced. If multiple, multiple drafts are produced in dependency order (cleanup/removal → config → docs → code).
- Each draft is approved separately before moving to the next.
- Confirm branch safety before staging or committing.
- Refuse direct commits on `main` or `master` unless explicitly overridden.
- One draft = one logical responsibility.
- Reject commit subjects that combine multiple outcomes, especially subjects containing ` and ` or ` & `.
- Run required checks before final confirmation.

### Pull Request Process

1. Create feature branch
Expand Down Expand Up @@ -329,3 +353,37 @@ Use skills when:
- Note common patterns that need skills
- Update documentation based on usage
- Refine prompts based on results

---

## Permissions & Guardrails (Balanced-Strict)

### Approval Gates

The assistant should ask before:
- **Destructive operations**: `rm`, force push, branch deletion, mass rewrites
- **Architecture changes**: new dependencies, new services, schema changes, public API changes
- **Commits and pushes**: always show proposed commit message, never auto-push
- **PR creation**: always show draft title/body, get confirmation

The assistant should proceed autonomously for:
- Reading, searching, listing files
- Routine edits to existing code (same pattern, same structure)
- Running tests and linters
- Running git status, diff, log (read-only git commands)

### Safer Commands

- `/commit`: plan-only — show commit draft for approval, user executes outside the command
- `/pr`: plan-only — show PR draft for approval, user executes outside the command
- `/fix`: reproduce -> diagnose -> propose -> approve -> fix -> verify
- `/spec`: load TaskManager, generate spec from the plan, show summary, save after approval
- `/review`: findings-first, no edits unless asked

### Workflow Principles

1. **Show before doing**: Always present the plan before executing.
2. **Minimal changes**: Fix the root cause, not symptoms. One change at a time.
3. **Verify after**: Run relevant tests after changes. Report results.
4. **No secrets**: Never commit or expose .env, keys, or credentials.
5. **Incremental over batch**: Do one thing, verify, then proceed.
31 changes: 20 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Control your AI patterns. Get repeatable results.

This repository is a production-oriented OpenCode configuration that applies the OpenAgents Control workflow: context-aware planning, approval gates, modular delegation, and consistent implementation standards.
This repository is a production-oriented OpenCode configuration inspired by useful OpenAgents Control ideas: context-aware planning, approval gates, modular delegation, and consistent implementation standards.

If you’ve ever had AI generate code that _works_ but doesn’t match your architecture, naming, or quality bar, this config is built to solve exactly that.

Expand Down Expand Up @@ -36,7 +36,7 @@ External library lookups are supported via Context7 workflows, helping avoid out

- **Core agents** for general execution and coding workflows
- **Specialized subagents** for planning, implementation, testing, review, and documentation
- **Command system** for structured, repeatable workflows
- **Slash commands** for repeatable workflows: `/commit`, `/pr`, `/spec`, `/review`, `/fix`, `/context`
- **Context system** for standards, workflows, and project intelligence
- **Skill library** across frontend, backend, infra, security, testing, and documentation
- **Runtime config** through `opencode.json`
Expand Down Expand Up @@ -119,7 +119,7 @@ This config includes MCP (Model Context Protocol) connections for enhanced tooli

Context7 provides live documentation lookups so agents can fetch up-to-date library docs without relying on training data.

- Used by the `Context7` skill and `@researcher` agent
- Used by the `context7` skill and `@ExternalScout` agent
- Enables real-time library docs, code examples, and API references
- Configured in `opencode.json` under the `context7` key
- API key set via `CONTEXT7_API_KEY` in `.env`
Expand Down Expand Up @@ -149,12 +149,21 @@ GitHub MCP enables AI agents to interact with GitHub directly—creating issues,
## Example prompts

```text
@implementer build this endpoint using our API conventions
@code-reviewer review this diff for security and maintainability risks
@researcher compare library options for this feature
@explainer summarize this module and generate docs
@CoderAgent implement this bounded subtask using our API conventions
@CodeReviewer review this diff for security and maintainability risks
@ExternalScout compare current library options for this feature
@DocWriter summarize this module and generate docs
```

Common workflows are available as slash commands:

- `/commit` - produce one or more SRP commit drafts for approval (plan-only)
- `/pr` - draft and create a pull request
- `/spec` - turn a plan into a spec and task bundle via TaskManager
- `/review` - run a strict review on code or diffs
- `/fix` - reproduce, patch, and verify a bug
- `/context` - load relevant project context

---

## Core workflow model
Expand All @@ -175,7 +184,7 @@ This is intentionally optimized for reliability and maintainability over "fire-a

```text
agent/ # Core agents and specialized subagents
command/ # Slash commands and workflow entrypoints
commands/ # Slash commands and workflow entrypoints
config/ # Metadata and config support files
context/ # Standards, workflows, project intelligence
skills/ # Reusable capability modules
Expand All @@ -191,7 +200,7 @@ You can safely adapt this config to your team:

- Update context files in `context/project-intelligence/`
- Tune agent behavior in `agent/`
- Add workflow commands under `command/`
- Add workflow commands under `commands/`
- Extend capabilities through `skills/`

Tip: keep edits incremental and tested. If behavior changes significantly, document it in README or context notes.
Expand All @@ -214,13 +223,13 @@ No. You can keep only the skills and commands your team actively uses.

### Can I still use upstream OAC resources?

Yes. This repo is compatible with OAC workflows and patterns and can be evolved alongside upstream guidance.
Yes, but they are reference material now. Native OpenCode config, `commands/`, skills, and specialist agents are the active workflow.

---

## Attribution

Powered by [OpenAgents Control (OAC)](https://github.com/darrenhinde/OpenAgentsControl) by Darren Hinde.
Inspired by [OpenAgents Control (OAC)](https://github.com/darrenhinde/OpenAgentsControl) by Darren Hinde.

---

Expand Down
Loading