@ikieaneh/opencode-kit 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
  <br />
12
12
  <div align="center">
13
13
  <a href="https://github.com/RizkiRachman/opencode-kit">
14
- <img src="docs/images/logo.png" alt="Logo" width="80" height="80">
14
+ <img src="docs/images/logo.svg" alt="Logo" width="80" height="80">
15
15
  </a>
16
16
 
17
17
  <h3 align="center">opencode-kit</h3>
@@ -0,0 +1,123 @@
1
+ # Quickstart: Using opencode-kit as a Plugin
2
+
3
+ This guide creates a new project from scratch with opencode-kit as an OpenCode plugin.
4
+
5
+ ## Step 1: Create a project
6
+
7
+ ```sh
8
+ mkdir my-agent-project
9
+ cd my-agent-project
10
+ git init
11
+ ```
12
+
13
+ ## Step 2: Install the plugin
14
+
15
+ ```sh
16
+ npm install @ikieaneh/opencode-kit
17
+ ```
18
+
19
+ ## Step 3: Configure OpenCode
20
+
21
+ Create `opencode.json`:
22
+
23
+ ```json
24
+ {
25
+ "model": "your-model",
26
+ "plugin": [
27
+ "@ikieaneh/opencode-kit",
28
+ "superpowers"
29
+ ],
30
+ "agent": {
31
+ "orchestrator": {
32
+ "model": "your-model",
33
+ "skills": [
34
+ "orchestration-template",
35
+ "scoring-pipeline",
36
+ "verification-before-completion"
37
+ ],
38
+ "steps": 50,
39
+ "fallback_models": ["your-fallback-model"]
40
+ },
41
+ "planner": {
42
+ "model": "your-model",
43
+ "skills": ["brainstorming", "writing-plans", "system-analyst"],
44
+ "steps": 80,
45
+ "fallback_models": ["your-fallback-model"]
46
+ },
47
+ "task-manager": {
48
+ "model": "your-model",
49
+ "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
50
+ "steps": 100,
51
+ "fallback_models": ["your-fallback-model"]
52
+ },
53
+ "code-reviewer": {
54
+ "model": "your-model",
55
+ "skills": ["qa-expert", "security-expert"],
56
+ "steps": 80,
57
+ "fallback_models": ["your-fallback-model"]
58
+ },
59
+ "explorer": {
60
+ "model": "your-model",
61
+ "steps": 30,
62
+ "tools": { "postgres_*": false, "memory_*": false, "context7_*": false }
63
+ },
64
+ "librarian": {
65
+ "model": "your-model",
66
+ "steps": 30,
67
+ "tools": { "postgres_*": false, "memory_*": false, "graphify_*": false }
68
+ },
69
+ "leaner": {
70
+ "model": "your-model",
71
+ "skills": ["verification-before-completion", "qa-expert"]
72
+ }
73
+ }
74
+ }
75
+ ```
76
+
77
+ ## Step 4: Start working
78
+
79
+ Open the project in OpenCode. The plugin auto-loads:
80
+
81
+ 1. 8 skills registered automatically
82
+ 2. Orchestration contract injected into every session
83
+ 3. Pre-flight enforcement active (branch check, contract load)
84
+ 4. Scoring pipeline available after every delegation
85
+ 5. ADR generator for architectural decisions
86
+ 6. Telemetry tracking elapsed time per phase
87
+
88
+ ## Step 5: Set a goal
89
+
90
+ Edit `.opencode/orchestration/contract.json`:
91
+
92
+ ```json
93
+ {
94
+ "state": "INIT",
95
+ "requirements": {
96
+ "goal": "Add user authentication with JWT",
97
+ "acceptance_criteria": ["Users can register", "Users can login", "Tokens expire after 24h"]
98
+ }
99
+ }
100
+ ```
101
+
102
+ ## Step 6: Workflow runs itself
103
+
104
+ ```
105
+ INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVIEW_SCORED → COMPLETE
106
+ ```
107
+
108
+ Each phase transition requires score ≥ 70. Score < 50 → BLOCKED.
109
+
110
+ ## What you get
111
+
112
+ | Feature | Provider |
113
+ |---------|----------|
114
+ | Contract protocol | orchestration-template skill |
115
+ | Scoring pipeline | scoring-pipeline skill |
116
+ | ADR records | adr-generator skill |
117
+ | QA standards | qa-expert skill |
118
+ | Impact analysis | system-analyst skill |
119
+ | Token optimization | token-optimize skill |
120
+ | Verification gates | verification-before-completion skill |
121
+ | Post-task learning | learner skill |
122
+ | Telemetry | src/telemetry.sh |
123
+ | Rules enforcement | rules.json + validation.sh |
@@ -0,0 +1,117 @@
1
+ # Model Provider Configurations
2
+
3
+ Add these to your `opencode.json` to configure AI models for opencode-kit agents.
4
+
5
+ ## DeepSeek (via Sumopod)
6
+
7
+ ```json
8
+ {
9
+ "model": "sumopod/deepseek-v4-flash",
10
+ "provider": {
11
+ "sumopod": {
12
+ "npm": "@ai-sdk/openai-compatible",
13
+ "name": "Sumopod AI",
14
+ "options": {
15
+ "baseURL": "https://ai.sumopod.com/v1",
16
+ "apiKey": "sk-your-key"
17
+ },
18
+ "models": {
19
+ "deepseek-v4-flash": {
20
+ "name": "DeepSeek V4 Flash",
21
+ "options": {
22
+ "reasoningEffort": "high",
23
+ "textVerbosity": "low"
24
+ }
25
+ }
26
+ }
27
+ }
28
+ }
29
+ }
30
+ ```
31
+
32
+ ## OpenAI
33
+
34
+ ```json
35
+ {
36
+ "model": "gpt-4o",
37
+ "provider": {
38
+ "openai": {
39
+ "npm": "@ai-sdk/openai",
40
+ "models": {
41
+ "gpt-4o": { "name": "GPT-4o" },
42
+ "gpt-4o-mini": { "name": "GPT-4o Mini" }
43
+ }
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ ## Anthropic (Claude)
50
+
51
+ ```json
52
+ {
53
+ "model": "claude-sonnet-4-20250514",
54
+ "provider": {
55
+ "anthropic": {
56
+ "npm": "@ai-sdk/anthropic",
57
+ "models": {
58
+ "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
59
+ "claude-haiku-3-5-20241022": { "name": "Claude Haiku 3.5" }
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ## Google (Gemini)
67
+
68
+ ```json
69
+ {
70
+ "model": "gemini-2.5-flash",
71
+ "provider": {
72
+ "google": {
73
+ "npm": "@ai-sdk/google",
74
+ "models": {
75
+ "gemini-2.5-flash": { "name": "Gemini 2.5 Flash" },
76
+ "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
77
+ }
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ ## Agent Assignment Strategy
84
+
85
+ Use **cheaper models** for simple agents, **better models** for complex reasoning:
86
+
87
+ | Agent | Recommended Model | Why |
88
+ |-------|------------------|-----|
89
+ | orchestrator | Cheaper (orchestration, not deep thinking) | Delegates most work |
90
+ | planner | Better (architecture, impact analysis) | Needs deep reasoning |
91
+ | task-manager | Better (implementation, code quality) | Needs to write correct code |
92
+ | code-reviewer | Better (security, edge cases) | Needs sharp analysis |
93
+ | explorer | Cheaper (just searches) | Simple grep/glob |
94
+ | librarian | Cheaper (fetches docs) | Simple fetch operations |
95
+ | learner | Cheaper (analysis after the fact) | Post-processing only |
96
+ | fixer | Cheaper (bounded edits) | Well-defined scope |
97
+
98
+ Example with mixed models:
99
+
100
+ ```json
101
+ {
102
+ "agent": {
103
+ "orchestrator": {
104
+ "model": "sumopod/deepseek-v4-flash",
105
+ "fallback_models": ["gpt-4o-mini"]
106
+ },
107
+ "planner": {
108
+ "model": "gpt-4o",
109
+ "fallback_models": ["sumopod/deepseek-v4-flash"]
110
+ },
111
+ "task-manager": {
112
+ "model": "gpt-4o",
113
+ "fallback_models": ["sumopod/deepseek-v4-flash"]
114
+ }
115
+ }
116
+ }
117
+ ```
@@ -0,0 +1,9 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" fill="none">
2
+ <rect width="80" height="80" rx="16" fill="#1a1a2e"/>
3
+ <path d="M20 25h40v30H20z" stroke="#e94560" stroke-width="2" fill="none"/>
4
+ <path d="M20 40h40" stroke="#e94560" stroke-width="2"/>
5
+ <circle cx="30" cy="35" r="3" fill="#0f3460"/>
6
+ <circle cx="50" cy="35" r="3" fill="#0f3460"/>
7
+ <path d="M25 48l10-10M45 48l10-10" stroke="#16213e" stroke-width="2"/>
8
+ <text x="40" y="62" text-anchor="middle" font-size="8" fill="#e94560" font-family="monospace">KIT</text>
9
+ </svg>
@@ -0,0 +1,55 @@
1
+ # Plugin Architecture — Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
4
+
5
+ **Goal:** Convert opencode-kit from a per-project scaffold to a global OpenCode plugin with local-override config
6
+
7
+ **Architecture:** Pure JS plugin (superpowers pattern) using `@opencode-ai/plugin` SDK. Global config at `~/.config/opencode-kit/`, project override at `.opencode/`. Plugin registers skills + system prompt transform.
8
+
9
+ **Tech Stack:** Node.js, @opencode-ai/plugin SDK, shell scripts
10
+
11
+ ---
12
+
13
+ ### Task 1: Plugin Entry Point
14
+
15
+ **Files:**
16
+ - Create: `.opencode/plugins/opencode-kit.js` — main plugin JS
17
+ - Create: `.claude-plugin/plugin.json` — metadata
18
+ - Modify: `package.json` — add plugin entry, `@opencode-ai/plugin` dependency
19
+
20
+ - [ ] Create `.opencode/plugins/opencode-kit.js` — system prompt transform hook that injects contract loading + preflight
21
+ - [ ] Create `.claude-plugin/plugin.json` — name, description, version, author
22
+ - [ ] Update `package.json` — `"main": ".opencode/plugins/opencode-kit.js"`, add `@opencode-ai/plugin` dep
23
+
24
+ ### Task 2: Global Config Resolution
25
+
26
+ **Files:**
27
+ - Create: `src/global-config.sh` — resolve config from local → global → plugin default
28
+
29
+ - [ ] Write resolution chain: `.opencode/` → `~/.config/opencode-kit/` → plugin `templates/`
30
+ - [ ] Add `init-global` command to copy plugin defaults to `~/.config/opencode-kit/`
31
+
32
+ ### Task 3: Plugin Schema
33
+
34
+ **Files:**
35
+ - Create: `templates/opencode-kit.schema.json` — validate opencode.json agent config
36
+
37
+ - [ ] Schema defines default agents (orchestrator, planner, task-manager, etc.)
38
+ - [ ] Documents plugin ordering requirement (must be first in plugin array)
39
+
40
+ ### Task 4: Init Coexistence
41
+
42
+ **Files:**
43
+ - Modify: `src/init.sh` — detect plugin, skip plugin-handled tasks
44
+
45
+ - [ ] If plugin detected (via `.opencode/plugins/opencode-kit.js`), skip skill/agent scaffolding
46
+ - [ ] Only scaffold per-project data: contract.json goal/scope, STATE.md, PROJECT.md
47
+
48
+ ### Task 5: Documentation
49
+
50
+ **Files:**
51
+ - Modify: `README.md` — plugin installation, ordering requirement
52
+ - Modify: `CHANGELOG.md`
53
+
54
+ - [ ] Add "Install as plugin" section to README
55
+ - [ ] Document global vs local resolution
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ikieaneh/opencode-kit",
3
- "version": "0.5.1",
3
+ "version": "0.5.2",
4
4
  "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
5
5
  "license": "MIT",
6
6
  "author": "RizkiRachman",
@@ -20,7 +20,8 @@
20
20
  "src/",
21
21
  "rules/",
22
22
  "templates/",
23
- "skills/"
23
+ "skills/",
24
+ "docs/"
24
25
  ],
25
26
  "publishConfig": {
26
27
  "access": "public"
@@ -0,0 +1,66 @@
1
+ ---
2
+ description: Java/Spring Boot conventions for opencode-kit projects. Hexagonal architecture, ArchUnit, Maven build.
3
+ ---
4
+
5
+ # Java Developer
6
+
7
+ Load this skill if your project uses **Java + Spring Boot + Maven**.
8
+
9
+ ## Build & Test
10
+
11
+ Replace generic `npm` commands with Maven equivalents:
12
+
13
+ | Generic | Java Equivalent |
14
+ |---------|-----------------|
15
+ | `npm test` | `mvn test` |
16
+ | `npm run build` | `mvn compile` |
17
+ | `npm run format` | `mvn spotless:apply` |
18
+ | `npm test -- --all` | `mvn verify` |
19
+
20
+ ## Quality Gates (run in order)
21
+
22
+ ```sh
23
+ mvn spotless:apply # Formatting (Google Java Style)
24
+ mvn test # ArchUnit (7 rules) + unit tests
25
+ mvn verify # SpotBugs + PMD CPD + full tests
26
+ ```
27
+
28
+ ## Agent Permission Overrides
29
+
30
+ In `opencode.json`, add Maven permissions to agents:
31
+
32
+ ```json
33
+ "bash": {
34
+ "mvn test*": "allow",
35
+ "mvn compile*": "allow",
36
+ "mvn verify": "allow",
37
+ "mvn spotless:apply": "allow",
38
+ "git diff*": "allow",
39
+ "git log*": "allow"
40
+ }
41
+ ```
42
+
43
+ ## Conventions
44
+
45
+ ### Hexagonal Architecture
46
+ ```
47
+ application/ → domain model, ports, domain services
48
+ infrastructure/ → web adapters, persistence, event handlers
49
+ ```
50
+
51
+ ### Writing Order
52
+ Port → Service → Mapper → Adapter → Constants → Events → Tests
53
+
54
+ ### Domain Models
55
+ - `@Builder @Getter @Setter` — zero JPA annotations
56
+ - Ports return **nullable**, never `Optional<T>`
57
+ - No JPA relationship annotations (`@ManyToOne`, `@OneToMany`, etc.)
58
+
59
+ ### ArchUnit Rules (7)
60
+ 1. domainMustNotDependOnInfrastructure
61
+ 2. domainModelsMustNotHaveJpaAnnotations
62
+ 3. portsMustNotReturnOptional
63
+ 4. entitiesMustNotUseJpaRelationshipAnnotations
64
+ 5. layeredArchitectureShouldRespectHexagonalBoundaries
65
+ 6. domainServicesMustBeAnnotatedWithService
66
+ 7. repositoryAdaptersMustBeAnnotatedWithComponent
package/src/init.sh CHANGED
@@ -1,6 +1,8 @@
1
1
  #!/usr/bin/env bash
2
2
  # opencode-kit init — scaffold orchestration framework into target project
3
- # Usage: npx opencode-kit init [--force]
3
+ # Usage: npx opencode-kit init [--force] [--sample]
4
+ # --force Overwrite existing .opencode/ (backs up to .opencode.bak.<timestamp>)
5
+ # --sample Also create a sample opencode.json with @ikieaneh/opencode-kit plugin config
4
6
  set -euo pipefail
5
7
 
6
8
  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -14,7 +16,14 @@ YELLOW='\033[1;33m'
14
16
  CYAN='\033[0;36m'
15
17
  NC='\033[0m'
16
18
 
17
- FORCE="${1:-}"
19
+ FORCE=false
20
+ SAMPLE=false
21
+ for arg in "$@"; do
22
+ case "$arg" in
23
+ --force) FORCE=true ;;
24
+ --sample) SAMPLE=true ;;
25
+ esac
26
+ done
18
27
  TARGET_DIR="${PWD}"
19
28
  TIMESTAMP=$(date +%Y%m%d%H%M%S)
20
29
 
@@ -64,7 +73,7 @@ fi
64
73
 
65
74
  # --- Handle existing .opencode/ ---
66
75
  if [ -d ".opencode" ]; then
67
- if [ "$FORCE" = "--force" ]; then
76
+ if [ "$FORCE" = true ]; then
68
77
  BACKUP=".opencode.bak.$TIMESTAMP"
69
78
  echo ""
70
79
  echo -e "${YELLOW}⚠️ --force: Backing up existing .opencode/ to $BACKUP${NC}"
@@ -163,3 +172,43 @@ else
163
172
  echo -e "${RED}❌ Verification failed. Check errors above.${NC}"
164
173
  exit 1
165
174
  fi
175
+
176
+ # --- Sample opencode.json ---
177
+ if [ "$SAMPLE" = true ]; then
178
+ if [ -f "opencode.json" ]; then
179
+ echo -e "${YELLOW} ⚠️ opencode.json already exists. Skipping sample.${NC}"
180
+ else
181
+ cat > opencode.json << 'SAMPLEEOF'
182
+ {
183
+ "model": "sumopod/deepseek-v4-flash",
184
+ "plugin": [
185
+ "@ikieaneh/opencode-kit",
186
+ "superpowers"
187
+ ],
188
+ "agent": {
189
+ "orchestrator": {
190
+ "model": "sumopod/deepseek-v4-flash",
191
+ "skills": ["orchestration-template", "scoring-pipeline", "verification-before-completion"],
192
+ "steps": 50
193
+ },
194
+ "planner": {
195
+ "model": "sumopod/deepseek-v4-flash",
196
+ "skills": ["brainstorming", "writing-plans", "system-analyst"],
197
+ "steps": 80
198
+ },
199
+ "task-manager": {
200
+ "model": "sumopod/deepseek-v4-flash",
201
+ "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
202
+ "steps": 100
203
+ },
204
+ "code-reviewer": {
205
+ "model": "sumopod/deepseek-v4-flash",
206
+ "skills": ["qa-expert", "security-expert"],
207
+ "steps": 80
208
+ }
209
+ }
210
+ }
211
+ SAMPLEEOF
212
+ echo " ✅ Sample opencode.json created"
213
+ fi
214
+ fi
@@ -13,9 +13,9 @@ permission:
13
13
  "*": ask
14
14
  "git diff*": allow
15
15
  "git log*": allow
16
- "mvn test*": allow
17
- "mvn compile*": allow
18
- "mvn verify": allow
16
+ "npm test": allow
17
+ "npm run build": allow
18
+ "npm test": allow
19
19
  task:
20
20
  "*": deny
21
21
  ---
@@ -11,9 +11,9 @@ permission:
11
11
  list: allow
12
12
  bash:
13
13
  "*": ask
14
- "mvn spotless:apply": allow
15
- "mvn test*": allow
16
- "mvn compile*": allow
14
+ "npm run format": allow
15
+ "npm test": allow
16
+ "npm run build": allow
17
17
  "git diff*": allow
18
18
  task:
19
19
  "*": deny
@@ -36,7 +36,7 @@ permission:
36
36
  ## Permissions
37
37
  - Read: All project files
38
38
  - Write: Scoped to assigned task only
39
- - Execute: mvn spotless:apply, mvn test/compile, git diff
39
+ - Execute: test commands, git diff, format/lint
40
40
  - Cannot: Spawn subagents, push to git, modify CI/CD
41
41
 
42
42
  You are a **fast implementation specialist for well-defined bounded tasks**. You do NOT research, make decisions, or expand scope.
@@ -45,7 +45,7 @@ You are a **fast implementation specialist for well-defined bounded tasks**. You
45
45
  1. Read assigned scope only
46
46
  2. Follow project conventions (writing order, naming)
47
47
  3. Make changes efficiently
48
- 4. Run spotless:apply + mvn compile on affected modules
48
+ 4. Run format + compile on affected modules
49
49
  5. Do NOT expand scope or make unsolicited improvements
50
50
 
51
51
  ## Output Format
@@ -11,10 +11,10 @@ permission:
11
11
  webfetch: allow
12
12
  bash:
13
13
  "*": ask
14
- "mvn test*": allow
15
- "mvn compile*": allow
16
- "mvn verify": allow
17
- "mvn spotless:apply": allow
14
+ "npm test": allow
15
+ "npm run build": allow
16
+ "npm test": allow
17
+ "npm run format": allow
18
18
  "git diff*": allow
19
19
  "git log*": allow
20
20
  task:
@@ -94,7 +94,7 @@ Delegate to @code-reviewer. After return → Scoring Pipeline → update contrac
94
94
  3. **Tier 3 (Verdict)**: ≥70 PASS, 50-69 RETRY, <50 BLOCKED
95
95
 
96
96
  ### 5. Verify (loop)
97
- Run quality gates (mvn test, mvn verify, etc.)
97
+ Run quality gates (verification-before-completion skill)
98
98
  If CRITICAL findings → BLOCK, fix, re-review. Max 3 iterations.
99
99
 
100
100
  ### 6. Ship
@@ -11,10 +11,10 @@ permission:
11
11
  webfetch: allow
12
12
  bash:
13
13
  "*": ask
14
- "mvn test*": allow
15
- "mvn compile*": allow
16
- "mvn verify": allow
17
- "mvn spotless:apply": allow
14
+ "npm test": allow
15
+ "npm run build": allow
16
+ "npm test": allow
17
+ "npm run format": allow
18
18
  "git diff*": allow
19
19
  "git log*": allow
20
20
  task:
@@ -40,7 +40,7 @@ permission:
40
40
  ## Permissions
41
41
  - Read: All project files
42
42
  - Write: Source files, test files
43
- - Execute: mvn commands, git diff/log, spotless
43
+ - Execute: git diff/log, spotless
44
44
  - Cannot: Push to git, modify .opencode/ config
45
45
 
46
46
  You implement plans step by step. Follow conventions exactly.
@@ -76,7 +76,7 @@ For each file:
76
76
  - Cover: happy path, empty, null, boundary, every error branch
77
77
 
78
78
  ### 5. Before Moving On
79
- - `mvn spotless:apply`
79
+ - Format code (spotless, prettier, etc.)
80
80
  - Remove debug code, TODOs, commented-out code
81
81
 
82
82
  ### 6. Output Format