v0.4.0 -- Framework Hardening

[striderZA]

Summary

Complete framework hardening milestone: agents, skills, commands, testing, plugins, rules, and documentation all improved for the OpenCode Game Studios template. Godot-first, multi-engine ready.

What Changed

Agents (15 files, +1,598 lines)

• Rewrites: ai-programmer, ui-programmer, engine-programmer, gameplay-programmer with Godot patterns
• Patches: 4 Godot specialists, 4 general agents, 3 leadership agents
• Compliance: 41/49 agents (83.7%) have all 4 structural sections

Skills (2 files, +198 lines)

• balance-check: parallel specialist delegation, cross-domain impact analysis
• asset-audit: file size budgets, format verification, specialist review

Commands (50 files, +425 lines)

• Created .opencode/commands/ with 50 commands across 9 categories

Agent Testing (4 files, +564 lines)

• tests/agents/validate.mjs + CI workflow
• tests/agents/validate-gdscript.mjs GDScript linter

Plugin Expansion (3 files, +768 lines)

• drift-detector.ts, changelog-generator.ts, plugin README

Rules (11 files, +343 lines)

• All rules hardened with examples, anti-patterns, cross-references

Documentation (5 files, +853 lines)

• CONTRIBUTING.md, authoring-agents.md, authoring-skills.md
• Updated AGENTS.md and README.md

Closes #34, #35, #36, #37, #38, #39, #40

[github-actions]

PR Review: v0.4.0 Framework Hardening

This is a substantial, well-organized PR. The structural changes (50 commands, 4 rewritten agents, CI pipeline, validation framework, drift detection) create a solid foundation. Key findings:

---

🐛 Potential Bugs

1. tests/agents/validate.mjs:409 — Division by zero risk

return `**Coverage**: ${((totalPassed / totalTests) * 100).toFixed(1)}%\n`;

If all validation sections error out, totalTests = 0, producing "NaN%" without an error signal. Add a guard:

const coverage = totalTests > 0 ? (totalPassed / totalTests) * 100 : 0;

2. .github/workflows/agent-validation.yml:14-15 — Action versions likely wrong

- uses: actions/checkout@v6
- uses: actions/setup-node@v6

@v6 doesn't exist for these actions — latest stable is @v4. This will fail CI on push.

3. .opencode/plugins/changelog-generator.ts:164 — Dead exported function
updateChangelogFile is exported but never called. The plugin only logs changelog previews; it never writes CHANGELOG.md. Either remove it or wire it into a command hook.

4. validate.mjs:58-75 — Frontmatter parser silently drops multi-line values
YAML values spanning multiple lines (indented on subsequent lines) are ignored. The regex ^(\w[\w-]*):\s*(.*) only captures the first line. If any agent introduces multi-line frontmatter values, the validator will silently miss-check them.

---

🔧 Code Quality Issues

5. Massive duplication: Collaboration Protocol (~50 lines × 4 agents)
ai-programmer.md:12-60, engine-programmer.md:12-60, gameplay-programmer.md:12-60, ui-programmer.md:12-60 are near-identical, including the 6-step Implementation Workflow and Collaborative Mindset bullet list. ~200 lines of duplicated content. Consider extracting to a shared include or reducing the template per-agent (letting domain-specific content carry the differentiation).

6. changelog-generator.ts:224,228 — Redundant computation
The session.idle handler calls generateChangelogs() on line 224, then immediately calls getLastTag() + parseConventionalCommits() again on lines 227-228. generateChangelogs already returns the parsed result — reuse the returned internal/player strings instead of re-querying git.

7. validate-gdscript.mjs — Always exits 0
Line 133: process.exit(0) even when issues are found. The comment says "advisory," but this means GDScript lint failures produce no CI signal. Consider a flag (--strict) or at minimum log a warning with non-zero exit when all files have issues.

8. validate.mjs:61 — lines split doesn't handle Windows line endings

const lines = match[1].split('\n');

On Windows (\r\n), the last field value would include a trailing \r. Use split(/\r?\n/) instead.

---

💡 Suggestions

9. Cross-reference validation is incomplete for skills
validate.mjs:205 validates subagent_type references in skill files, but uses a regex that won't catch all patterns. Backtick-quoted references like subagent_type: `game-designer` would have the backticks stripped by the .replace(/\/g,'')on line 207, but the regex match depends on optional backticks inside capture groups. The simpler approach: stripsubagent_type:` prefix + trim + strip backticks, then validate against agent names.

10. Consider adding a per-rule path test in validate.mjs
Rules files declare path scopes (e.g. paths: ["src/ai/**"]). The validator doesn't check whether these paths actually exist in the project or whether the paths overlap. Adding this would catch stale rules.

11. validate.mjs:328 — Section with error is counted as total = 0
When a section errors (directory not found), totalPassed/totalFailed/totalTests are all skipped due to the continue on line 343. The summary table will show 0 | 0 | 0 for that section and lower overall totalTests. If you want to reflect that the section is "checked but failing," consider incrementing totalFailed on error.

---

Summary

Category	Count
Potential bugs	4
Code quality	4
Suggestions	3

Overall: Well-structured PR with good validation tooling. The most impactful fixes are the action version pins (#2), the division-by-zero guard (#1), and deduplicating the Collaboration Protocol (#5) before it diverges across the 4 programmer agents.

opencode session  |  github run

[github-actions]

Here is my review of PR v0.4.0 — Framework Hardening.

---

Review Summary

This is a large, well-structured PR (91 files, +4784/−434). The validation framework, drift detector, changelog generator, 50 command stubs, and agent rewrites establish a solid foundation.

---

Issues Found

Some of these differ from the existing PR review comments.

1. validate.mjs:409 — Division by zero (was already noted)
Line 408 already has a ternary guard (totalTests > 0 ? ... : '0.0'), so this is actually already fixed in the version I see on disk. The updateChangelogFile dead export (#3 in the prior review) is also unused but harmless. Let me verify on disk... yes, the guard is present. Good.

2. validate-gdscript.mjs:133 — Advisory-only exit hides CI breaks
The script always exits 0 unless --strict is passed. Default mode prints issues but gives no CI signal. If GDScript patterns drift over time, this produces a silent regression. Recommendation: default to non-zero exit when issues are found, or at minimum surface the --strict flag prominently in CI.

3. validate.mjs:65 — \r in value from YAML lines
The regex match[1].split(/\r?\n/) at line 61 is already correct (handles both \n and \r\n). However, individual KV values could still contain trailing \r if the file uses \r\n — but .trim() on line 68 strips that. So this is actually fine. (prior review callout was a false positive on this one)

4. validate.mjs:66 — Multi-line YAML values silently dropped
Confirmed: the regex ^(\w[\w-]*):\s*(.*) only captures the first line. If any agent introduces multi-line frontmatter values (e.g., a YAML array spanning multiple lines), the validator silently ignores subsequent lines. Low risk currently since frontmatter values are all single-line, but it's a latent bug.

5. Massive Collaboration Protocol duplication (~50 lines × 4 agents)
Confirmed — ai-programmer.md:12-17, engine-programmer.md:12-17, gameplay-programmer.md:12-17, ui-programmer.md:12-17 are near-identical. All start with "You are a collaborative implementer, not an autonomous code generator." and reference docs/authoring-agents.md. The only differentiation is the 3 architecture questions specific to each domain. Consider extracting the boilerplate to a shared include or reducing to a one-liner.

6. changelog-generator.ts:224,228 — Redundant git queries (as noted)
The session.idle handler calls generateChangelogs() on line 224, which internally calls getLastTag() + parseConventionalCommits(). Then the result is discarded (only checked for "No changes" string). If a follow-up command needs the parsed data, this is wasted work. Minor — tradeoff is code simplicity.

7. drift-detector.ts:46, 48 — Same YAML limited parsing
Same regex limitation as validate.mjs — only single-line YAML values. No current impact since all frontmatter values are single-line, but duplicates the same architectural limitation.

8. validate.mjs:343 — Section errors zero out totals (as noted)
When a section errors (e.g., directory not found), continue skips incrementing any counter. The summary table shows the section as 0 | 0 | 0. The error is logged in the report, but the total test count is lower than expected. If you want the error to affect the verdict, increment totalFailed here.

9. tests/agents/validate.mjs:27-36 — Exceptions list is fragile
8 UE/Unity agent files are in AGENT_EXCEPTIONS. The logic is correct, but if those agents are later fixed and someone forgets to remove them from the list, they get a PASS + a warning (line 137). That's good, but there's no fix reminder mechanism. Consider adding a counter at the top of the report: "8 agents still excepted".

10. validate.mjs:204-211 — subagent_type cross-reference parsing is fragile
The regex subagent_type:\s*\?([a-z][\w-]+)`?can also matchsubagent_type: generalinside prose. Line 207 strips backticks, but if a tool call hassubagent_type: "general"(with quotes), the regex won't match the quotes and the value could be"general"(with quotes) which won't match any agent name"general"`. This would produce a false positive issue. Consider a more robust parser.

---

What's Done Well

• CI workflow is clean and well-structured (@v4 actions, Node 20, artifact upload)
• Validation report format is clear and useful (PASS/FAIL/EXCEPTED with warnings)
• Drift detector is a nice real-time complement to the CI-time validator
• 50 command stubs all have consistent frontmatter with cross-validation
• The 11 rules files all received concrete examples and anti-patterns
• validate-gdscript.mjs has good pattern checks (yield → await, untyped vars, get_node)

---

Verdict

Changes requested — no critical blockers, but several issues should be addressed before merging:

1. GDScript validator defaulting to exit 0 (chore(deps): bump actions/stale from 9 to 10 #2)
2. Multi-line YAML parsing gap (Fix: Replace AskUserQuestion with question tool in skill files #4) — at minimum document the limitation
3. Extract duplicated Collaboration Protocol boilerplate (Fix: Replace .claude/ path references with .opencode/ in skills and docs #5)
4. Section error counting inconsistency (Polish: Update agent tool references from Write/Edit to write and edit #8)

opencode session  |  github run

[github-actions]

PR Review: v0.4.0 — Framework Hardening

Previous Review Corrections

The earlier reviews made several incorrect claims:

1. "Division by zero at validate.mjs:409" — False positive. Line 411 already has totalTests > 0 ? ... : '0.0' guard. Handled correctly.

2. "Action versions @v6" — False positive. The CI workflow uses actions/checkout@v4 and actions/setup-node@v4, which are correct.

3. "validate-gdscript always exits 0" — Incorrect. It exits 1 by default on issues (line 140). The --advisory flag makes it exit 0. The real issue is it's not wired into CI — only validate.mjs runs in agent-validation.yml.

4. "\r in YAML values" — False positive. .trim() on line 71 strips trailing \r. Already handled.

---

New Issues

1. changelog-generator.ts:164-179 — Dead code
updateChangelogFile is exported but never called by any hook. The plugin only logs a preview message. Clean it up or wire it into a command hook.

2. drift-detector.ts vs validate.mjs — ~80% logic duplication
The drift detector reimplements the exact same frontmatter parsing (parseFrontmatter), section validation, and field requirement checks as validate.mjs. If the template requirements change, both must be updated. Extract the common validation logic into a shared module.

3. validate.mjs:52 — name field in command frontmatter is not validated
All 50 command stubs include a name field in their frontmatter, but REQUIRED_COMMAND_FRONTMATTER only checks ['description', 'skill', 'category']. A missing name would go undetected.

4. CI workflow only triggers on development pushes

on:
  push:
    branches: [development]

After merge to master, pushes to master won't run validation. Consider adding master to push triggers, or rely solely on the pull_request trigger.

5. validate-gdscript.mjs — get_node check has false positive potential
Line 62: !trimmed.includes('#') is meant to exclude commented-out lines, but # could appear mid-line in a string. Use /^\s*#/ (checks # is at line start) or trimmed.startsWith('#') instead.

6. prototyper.md — Heading level mismatch
Uses ### Collaboration Protocol (H3) directly under prose text. All other 48 agents use ## Collaboration Protocol (H2). The validator only checks string inclusion (not heading level), so this passes CI. Causes inconsistent rendered TOC structure.

7. README.md:47 vs badges — Skill count mismatch
Line 47: "its 49 agents, 73 skills, 12 hooks"
Badge at line 11: skills-75
AGENTS.md and command table reference 75 skills. One of these is wrong.

8. Section validation is order-agnostic
validate.mjs checks that section names exist in file content, but never verifies they appear in the expected order. An agent could list sections in reverse order and pass.

---

Strengths

• Clean CI config with artifact upload and correct if: always() for report generation
• Exception list pattern (AGENT_EXCEPTIONS) is well-designed — waives blockers while tracking debt
• Rules expansion with Examples, Anti-Patterns, and Cross-References sections is excellent
• validate-gdscript.mjs has practical Godot 4 patterns (yield→await, typed vars, @onready)
• 50 command stubs with consistent frontmatter and cross-validation to skill directories

Verdict

Changes requested — Most issues are minor. The blocker is the dead updateChangelogFile export (#1) and the missing name field validation (#3). Recommend:

1. Remove dead export or wire it up
2. Add name to REQUIRED_COMMAND_FRONTMATTER
3. Add validate-gdscript.mjs to CI pipeline
4. Fix the 73→75 skill count in README.md

opencode session  |  github run