Skip to content
This repository was archived by the owner on May 23, 2026. It is now read-only.

Commit cdae139

Browse files
JRedekerJRedeker
committed
feat: scaffold OpenCode Advance repository
Initial commit establishing the OpenCode Advance project — the declarative, Go-based rewrite of open-chad. Paired with the Advance plugin as a required dependency, OCA owns the environment, installer, and configuration layer while Advance owns the spec-driven workflow. This scaffold contains: - Brand identity: wordmark spec (GBA-stylized "ADVANCE"), Obsidian/Slate/ Graphite palette with signature frosted indigo (#6C7AB8) accent, Obsidian theme specification for OpenCode UI and tmux status bar - Architecture: full system design doc covering the stack.toml-driven config model, Advance delegation pattern, clean cutover policy, and the Go package boundaries (config/render/health/migrate) - Schema reference: complete stack.toml schema with variable interpolation, provides-based asset ownership, and plugin lifecycle fields - CLI surface: full oca command reference (apply/diff/doctor/pin/update/ migrate/session/theme/discord/install/uninstall) - v1 implementation proposal: problem statement, success criteria, constraints, approach, 7-phase sequencing, risks, deliverables - First-boot instructions: how to initialize ADV state in this repo and create the first ADV change from the scaffolded proposal - Directory skeleton: cmd/oca, internal/{config,render,health,migrate}, assets/{agents,instructions,skills,themes}, templates/, bin/, lib/, tests/, docs/{design,proposals}, .adv/{specs,changes,archive} - Working stack.example.toml grounded in the maintainer's real 9-server MCP stack, 6-plugin loadout, 11-instruction set, and provider/agent config - Go module scaffold with placeholder main.go that builds cleanly, Makefile with standard targets, CI workflow running vet/fmt/test on push/PR - AGENTS.md reference for developers and AI agents working in this repo No implementation code yet. Phase 0 (foundation + brand primitives) begins as the first ADV change, driven from docs/proposals/first-boot.md. Clean cutover policy is in effect: this repo MUST NOT modify any user-level OpenCode config until v1.0 release. All development uses isolated config directories via OCA_* environment overrides.
0 parents  commit cdae139

36 files changed

Lines changed: 3496 additions & 0 deletions

File tree

‎.adv/archive/.gitkeep‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# This directory holds archived ADV changes after /adv-archive runs.
2+
# Populated by the ADV plugin. Empty by design.

‎.adv/changes/.gitkeep‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# This directory holds active ADV change proposals. Populated by the ADV
2+
# plugin when /adv-proposal creates a new change. Empty by design.

‎.adv/specs/.gitkeep‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# This directory holds capability specs written by the ADV plugin.
2+
# When you first run /adv-status in OpenCode from this repo, the plugin
3+
# will populate it as needed. Empty by design.

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [trunk]
6+
pull_request:
7+
branches: [trunk]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
scaffold-check:
14+
name: Scaffold build
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Go
21+
uses: actions/setup-go@v5
22+
with:
23+
go-version: '1.22'
24+
check-latest: true
25+
26+
- name: Verify gofmt
27+
run: |
28+
if [ -n "$(gofmt -l .)" ]; then
29+
echo "::error::gofmt violations detected"
30+
gofmt -l .
31+
exit 1
32+
fi
33+
34+
- name: Vet
35+
run: go vet ./...
36+
37+
- name: Build
38+
run: go build ./...
39+
40+
- name: Test
41+
run: go test ./...

‎.gitignore‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# ─── Go build artifacts ──────────────────────────────────────────────────────
2+
/bin/oca
3+
/bin/oca-*
4+
/dist/
5+
*.exe
6+
*.test
7+
*.out
8+
*.prof
9+
coverage.*
10+
vendor/
11+
12+
# ─── Editor / IDE ────────────────────────────────────────────────────────────
13+
.vscode/
14+
.idea/
15+
*.swp
16+
*.swo
17+
*~
18+
.DS_Store
19+
20+
# ─── Environment / secrets ───────────────────────────────────────────────────
21+
.env
22+
.env.local
23+
*.env.local
24+
secrets/
25+
**/secrets/*.env
26+
stack.local.toml
27+
28+
# ─── Test / dev config isolation ─────────────────────────────────────────────
29+
# During development, oca writes into isolated test dirs instead of
30+
# ~/.config/opencode/. These live in .dev/ and are never committed.
31+
.dev/
32+
.dev-*/
33+
.opencode-advance-dev/
34+
.vision-dev/
35+
36+
# ─── ADV cache (derived state, not committed) ────────────────────────────────
37+
.adv/db/
38+
*.db
39+
*.db-wal
40+
*.db-shm
41+
42+
# ─── Logs / scratch ──────────────────────────────────────────────────────────
43+
*.log
44+
tmp/
45+
scratch/
46+
47+
# ─── Node artifacts (installer helpers may use node) ─────────────────────────
48+
node_modules/
49+
package-lock.json
50+
pnpm-lock.yaml
51+
bun.lock

‎AGENTS.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# AGENTS.md — Developer & Agent Reference
2+
3+
Internal reference for AI agents and human developers working on OpenCode Advance.
4+
For user-facing documentation, see [`README.md`](README.md).
5+
6+
---
7+
8+
## Project Overview
9+
10+
**OpenCode Advance** (`oca`) is the environment and configuration platform for [OpenCode](https://opencode.ai). It replaces the earlier `open-chad` project with a Go-based, declarative rewrite. It pairs with the [Advance](https://github.com/Sharper-Flow/Advance) spec-driven workflow plugin as a required dependency.
11+
12+
- **Repo**: `https://github.com/Sharper-Flow/Opencode-Advance.git`
13+
- **Branch**: `trunk` (default), remote `origin`
14+
- **Language**: Go 1.22+ (CLI core), Bash (tmux/shell integration only), Markdown (design docs, proposals)
15+
- **Test framework**: Go stdlib `testing` + golden files; bash test scripts for shell integration
16+
17+
---
18+
19+
## Relationship to Advance
20+
21+
OpenCode Advance depends on Advance; Advance does not depend on OpenCode Advance.
22+
23+
- OpenCode Advance clones, builds, and wires the Advance plugin as part of `oca install` / `oca apply`
24+
- OpenCode Advance delegates all Advance-owned asset sync to `advance/scripts/sync-global.sh --fix`
25+
- OpenCode Advance does **not** duplicate any files that Advance owns: `adv-*.md` commands, ADV agents (`plan`, `scout`, `refine`, `adv-researcher`, `tron`), ADV skills (`adv-*`), or ADV instructions
26+
- OpenCode Advance owns the non-ADV slice of the environment: environment-level agents (`build`, `explore`, `librarian`, `general`, `mechanic`), instructions (rules.yaml, identity, shell_strategy, etc.), MCP server lifecycle, plugin management, providers, session/tmux UX
27+
28+
This clean boundary is the central reason OpenCode Advance exists as a separate project. Each file in `~/.config/opencode/` has exactly one owner.
29+
30+
---
31+
32+
## Architecture
33+
34+
```
35+
opencodeadvance/
36+
├── stack.toml # THE source of truth (user creates; oca reads)
37+
├── stack.example.toml # Complete example reference
38+
│
39+
├── cmd/oca/ # CLI entry point (Go)
40+
│ └── main.go
41+
│
42+
├── internal/ # Internal Go packages
43+
│ ├── config/ # stack.toml parser + schema validation
44+
│ ├── render/ # Templates + JSON merge logic
45+
│ ├── health/ # MCP/plugin/instruction health checks
46+
│ └── migrate/ # open-chad → opencode-advance importer
47+
│
48+
├── assets/ # Static files, copied as-is to ~/.config/opencode/
49+
│ ├── agents/ # build.md, explore.md, librarian.md, general.md, mechanic.md
50+
│ ├── instructions/ # identity.md, rules.yaml, shell_strategy.md, etc.
51+
│ ├── skills/ # lgrep, mcp-selection, morph, worktree, prioritizer
52+
│ └── themes/
53+
│ ├── obsidian.json # OpenCode UI theme (obsidian palette, indigo accent)
54+
│ ├── obsidian.tmux.conf # Tmux 2-row status bar theme
55+
│ └── obsidian-light.tmux.conf # Optional light variant (future)
56+
│
57+
├── templates/ # Go text/template files rendered by oca apply
58+
│ ├── opencode.json.gotmpl # Merged into ~/.config/opencode/opencode.json
59+
│ ├── vision-servers.yaml.gotmpl # Rendered to ~/.config/vision/servers.yaml
60+
│ └── tmux.conf.block.gotmpl # Block injected into ~/.tmux.conf
61+
│
62+
├── bin/ # Shell-level entry points (post-install)
63+
│ ├── oca # Thin wrapper calling the Go binary
64+
│ ├── oc # Short alias (retains muscle memory)
65+
│ ├── cds # Scratch dir launcher
66+
│ └── ocashell.sh # Completion bootstrap
67+
│
68+
├── lib/ # Shell-only helpers (tmux theming, status bar)
69+
│ ├── obsidian.tmux.conf # Live theme file (also present in assets/)
70+
│ ├── status_bar.sh # Status bar renderer
71+
│ ├── boot_splash.sh # Boot splash with wordmark reveal
72+
│ ├── session_lifecycle.sh # tmux session teardown hooks
73+
│ └── discord/ # Discord Rich Presence integration
74+
│
75+
├── tests/ # Test suites
76+
│ ├── config_test.go # stack.toml parse/validate
77+
│ ├── render_test.go # Template rendering golden files
78+
│ ├── apply_test.go # End-to-end apply with mock home
79+
│ └── shell/ # Bash tests for shell integration
80+
│
81+
├── docs/
82+
│ ├── design/ # Architecture, brand, schema, CLI reference
83+
│ │ ├── architecture.md
84+
│ │ ├── brand.md
85+
│ │ ├── wordmark.md
86+
│ │ ├── palette.md
87+
│ │ ├── theme.md
88+
│ │ ├── stack-toml-schema.md
89+
│ │ └── cli-surface.md
90+
│ ├── proposals/ # Implementation planning docs
91+
│ │ ├── v1-implementation.md # Full v1.0 proposal content (for first ADV change)
92+
│ │ ├── phases.md # Phase sequencing
93+
│ │ └── first-boot.md # How to initialize ADV in this repo
94+
│ └── specs/ # Generated spec docs (populated by ADV)
95+
│
96+
├── .adv/ # ADV state directories (plugin-managed)
97+
│ ├── specs/ # Capability specs (written by ADV)
98+
│ ├── changes/ # Active change proposals (written by ADV)
99+
│ └── archive/ # Completed changes (written by ADV)
100+
│
101+
└── .github/
102+
└── workflows/ # CI (populated in Phase 1)
103+
```
104+
105+
---
106+
107+
## Development Model
108+
109+
This project is developed through the Advance spec-driven workflow. Every non-trivial change is an ADV change with:
110+
111+
- A proposal (problem statement, success criteria, constraints)
112+
- Research (validated architectural decisions)
113+
- Prep (task graph synthesized from research)
114+
- Apply (TDD-driven implementation)
115+
- Review (code review across multiple dimensions)
116+
- Harden (quality verification and cleanup)
117+
- Signoff (user approval)
118+
119+
The v1.0 initial implementation is scoped in [`docs/proposals/v1-implementation.md`](docs/proposals/v1-implementation.md) and phased in [`docs/proposals/phases.md`](docs/proposals/phases.md).
120+
121+
### First ADV change
122+
123+
See [`docs/proposals/first-boot.md`](docs/proposals/first-boot.md) for the exact sequence to initialize ADV state in this repo and create the first change from the scaffolded proposal content.
124+
125+
---
126+
127+
## Clean cutover policy
128+
129+
During development, OpenCode Advance MUST NOT modify the user's live OpenCode configuration. All development and testing happens in isolated config directories:
130+
131+
- `~/.config/opencode-advance-dev/` (instead of `~/.config/opencode/`)
132+
- `~/.config/vision-dev/` (instead of `~/.config/vision/`)
133+
- Isolated tmux socket if needed
134+
135+
The `oca` CLI accepts environment overrides for all target paths so tests and dev runs never touch production state:
136+
137+
| Override | Purpose |
138+
| ------------------------- | --------------------------------------------------------------- |
139+
| `OCA_OPENCODE_CONFIG_DIR` | Target OpenCode config dir (default: `~/.config/opencode`) |
140+
| `OCA_VISION_CONFIG_DIR` | Target Vision config dir (default: `~/.config/vision`) |
141+
| `OCA_PLUGIN_CHECKOUT_ROOT` | Where plugins are cloned (default: `~/dev/oc-plugins/`) |
142+
| `OCA_CACHE_DIR` | Cache/runtime dir (default: `$XDG_RUNTIME_DIR/opencode-advance`) |
143+
144+
At v1.0 release time, the user runs `oca migrate from-open-chad` which performs a one-shot read of the current `open-chad`-managed state, emits a `stack.toml` reflecting it, and then `oca install` applies it to production.
145+
146+
---
147+
148+
## What goes where (file ownership matrix)
149+
150+
| File / dir | Owner | Notes |
151+
| ------------------------------------------- | ------------- | -------------------------------------------------- |
152+
| `stack.toml` | **user** | Source of truth. User edits. `oca` reads. |
153+
| `~/.config/opencode/opencode.json` | **oca** | Rendered from stack.toml + plugin-provided fragments |
154+
| `~/.config/opencode/agents/build.md` | **oca** | Environment-level agent |
155+
| `~/.config/opencode/agents/explore.md` | **oca** | Environment-level agent |
156+
| `~/.config/opencode/agents/librarian.md` | **oca** | Environment-level agent |
157+
| `~/.config/opencode/agents/general.md` | **oca** | Environment-level agent |
158+
| `~/.config/opencode/agents/mechanic.md` | **oca** | Environment-level agent |
159+
| `~/.config/opencode/agents/plan.md` | **Advance** | ADV agent (via sync-global.sh) |
160+
| `~/.config/opencode/agents/scout.md` | **Advance** | ADV agent |
161+
| `~/.config/opencode/agents/refine.md` | **Advance** | ADV agent |
162+
| `~/.config/opencode/agents/adv-researcher.md` | **Advance** | ADV agent |
163+
| `~/.config/opencode/agents/tron.md` | **Advance** | ADV agent |
164+
| `~/.config/opencode/command/adv-*.md` | **Advance** | ADV slash commands |
165+
| `~/.config/opencode/command/oca-*.md` | **oca** | OpenCode Advance slash commands (if any) |
166+
| `~/.config/opencode/skills/adv-*/` | **Advance** | ADV methodology skills |
167+
| `~/.config/opencode/skills/lgrep/` | **oca** | Tool selection skills |
168+
| `~/.config/opencode/skills/morph/` | **oca** | Tool selection skills |
169+
| `~/.config/opencode/skills/prioritizer/` | **oca** | Shared methodology skill |
170+
| `~/.config/opencode/skills/worktree/` | **oca** | Shared methodology skill |
171+
| `~/.config/opencode/skills/mcp-selection/` | **oca** | Tool selection skill |
172+
| `~/.config/opencode/instructions/identity.md` | **oca** | Environment-level instruction |
173+
| `~/.config/opencode/instructions/rules.yaml` | **oca** | Environment-level instruction |
174+
| `~/.config/opencode/instructions/ADV_*.md` | **Advance** | Advance instruction (path referenced) |
175+
| `~/.config/vision/servers.yaml` | **oca** | Rendered from stack.toml |
176+
| `~/.tmux.conf` (OCA block only) | **oca** | Managed block, rest is user-owned |
177+
| `~/.zshrc` / `~/.bashrc` (OCA block only) | **oca** | Managed block, rest is user-owned |
178+
179+
Any file not in the "oca" or "Advance" column is user-owned and MUST NOT be touched by `oca apply`.
180+
181+
---
182+
183+
## Commit style
184+
185+
- Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `style:`
186+
- Scope when relevant: `feat(config): add stack.toml schema validation`
187+
- Atomic commits — one logical change per commit
188+
- Never commit secrets or user-specific paths
189+
190+
---
191+
192+
## CI/Release (Phase 1+)
193+
194+
To be populated in `.github/workflows/`:
195+
196+
- `ci.yml` — on every PR and push to trunk: `go test ./...`, `go vet ./...`, `gofmt -d .`
197+
- `release.yml` — on version tags (`v*`): goreleaser builds cross-platform binaries, publishes to GitHub Releases

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Sharper Flow
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# OpenCode Advance — Makefile
2+
#
3+
# Standard targets for local development. The real build pipeline runs in CI
4+
# via goreleaser (configured in Phase 7).
5+
6+
.PHONY: help build test vet fmt check clean scaffold-check
7+
8+
help:
9+
@echo "OpenCode Advance — Makefile targets"
10+
@echo ""
11+
@echo " build Build the oca binary to ./bin/oca"
12+
@echo " test Run all Go tests"
13+
@echo " vet Run go vet"
14+
@echo " fmt Run gofmt on all Go files"
15+
@echo " check Run vet + fmt + test (full verification)"
16+
@echo " scaffold-check Quick sanity check that the scaffold builds"
17+
@echo " clean Remove build artifacts"
18+
@echo ""
19+
20+
build:
21+
@mkdir -p bin
22+
go build -o bin/oca ./cmd/oca
23+
24+
test:
25+
go test ./...
26+
27+
vet:
28+
go vet ./...
29+
30+
fmt:
31+
gofmt -w .
32+
33+
fmt-check:
34+
@if [ -n "$$(gofmt -l .)" ]; then \
35+
echo "gofmt violations:"; \
36+
gofmt -l .; \
37+
exit 1; \
38+
fi
39+
40+
check: vet fmt-check test
41+
42+
scaffold-check: build
43+
@./bin/oca
44+
45+
clean:
46+
rm -rf bin/ dist/
47+
rm -f coverage.out

0 commit comments

Comments
 (0)