v0.3.1 — init-template skill + docs cleanup

[striderZA]

Summary

Two features: /init-template first-time setup skill + docs cleanup.

Changes

• New /init-template skill: 7-phase interactive workflow for transforming the cloned template into a clean game project
• Docs cleanup: Removed CLAUDE-local-template.md, settings-local-template.md (Claude Code specific). Rewrote setup-requirements.md, hooks-reference.md, context-management.md for OpenCode. Fixed deprecated AskUserQuestion, Write/Edit, .claude/ references across all docs.

Verification

• CI checks pass
• Review changes per commit

[github-actions]

PR Review: v0.3.1 — init-template skill + docs cleanup

I've read all 13 files. Here's my review organized by severity.

---

🐛 Potential Bugs

1. init-template/SKILL.md Phase 5 — Unconditional rm -rf is destructive
The skill instructs: rm -rf design/*, rm -rf src/*, rm -rf production/* without checking the working directory or confirming the user hasn't already added work. If someone clones the template, runs /brainstorm and then runs /init-template, their design docs are silently destroyed. At minimum, these should check the directory is empty first or skip if files exist with a warning.

2. quick-start.md — References deleted file
Line 290 in the File Structure Reference still lists settings-local-template.md. This file was deleted in this PR. The reference will mislead users.

3. setup-requirements.md — Stale instruction
Line 7 says "run /start before anything else" but the new first step is /init-template. This contradicts the quick-start guide's Path A step 2 and the new skill's purpose.

---

🔴 Code Quality Issues

4. init-template/SKILL.md Phase 3 — Vague model mapping instruction
"Replace the Model Mapping section at the top with the user's engine and model preference" lacks specifics. The skill doesn't describe the Model Mapping section's format, what to replace, or provide a reference template. The agent executing this has too much ambiguity.

5. init-template/SKILL.md — No error handling across phases
The skill assumes every operation succeeds. If AGENTS.md doesn't exist, if opencode.json is malformed, if git checkout --orphan fails — none of these are handled. Each phase should specify what to do on failure (abort, warn, skip).

6. quick-start.md — File structure references obsolete paths
Line 279 references .opencode/config.json (file is opencode.json at root) and .opencode/hooks/ (which was a Claude Code bash hooks pattern, replaced by the TypeScript plugin). These will mislead new users.

---

💡 Suggestions

7. Add existence guards to Phase 5 rm commands — Use patterns like [ -f src/main.ts ] && echo "WARNING: src/ not empty, skipping" rather than unconditional deletion.

8. Add a "smoke test" phase — After template initialization, automatically verify the project structure is correct (required dirs exist, README is populated, AGENTS.md has the right engine).

9. Consider adding opencode.json to the Phase 5 file list — The current setup requirements say opencode.json should be kept, but if this is a fresh init from template, are there any template-specific entries in it that should be cleaned?

10. init-template Phase 6 git reset — The orphan-branch reset is correct, but the instruction "Delete all old tags (optional)" should warn about remote implications if tags have been pushed.

---

Summary

Severity	Count
Bug (logic error)	3
Code quality	3
Suggestion	3

The AskUserQuestion → question, Write/Edit → write and edit, and Claude Code → OpenCode renaming across all docs is thorough and correctly done. The hooks-reference.md rewrite to reflect the TypeScript plugin architecture is accurate. The new skill is well-structured and covers the right phases. The main concerns are the destructive Phase 5 operations, the stale references in quick-start.md's file tree, and the vague Phase 3 model mapping instruction.

opencode session  |  github run

[striderZA]

All review items addressed:

Bug fixes:

1. Phase 5 rm -rf: Now guarded with existence checks — warns and skips if user content exists in design/, src/, or production/
2. quick-start.md line 292: Removed stale settings-local-template.md reference; fixed config.json→opencode.json and hooks/→plugins/
3. setup-requirements.md line 7: Changed /start to /init-template

Code quality:
4. Phase 3: Added specific instructions for AGENTS.md format (Technology Stack section, model mapping, engine)
5. Error handling: Added failure guidance across Phases 3-6 (warn and skip if files missing, warn on rm failure, warn on remote tags)

Suggestions:
7. Existence guards applied (see #1)
10. Git reset phase now warns about remote implications of tag deletion and force push

[github-actions]

All 10 review items have been verified against the current file state:

Fixed (8/10):

1. Phase 5 rm -rf guards — existence checks with warnings (SKILL.md:92-96)
2. quick-start.md stale refs — settings-local-template.md removed, opencode.json at root corrected (line 278), plugins/ correct (line 281)
3. setup-requirements.md — now references /init-template instead of /start (line 7)
4. Error handling — warn-and-skip across Phases 3-6 (SKILL.md:78,86,96)
5. Existence guards applied (SKILL.md:93-95)
6. opencode.json handled in Phase 4 (SKILL.md:82-86)
7. Remote warnings on git reset (SKILL.md:105-106)

Protocol files — All three (design-agent-protocol.md, implementation-agent-protocol.md, leadership-agent-protocol.md) correctly use question instead of AskUserQuestion and write and edit tools instead of Write/Edit. Hooks reference accurately describes the TypeScript plugin architecture.

Partially addressed:
4. Phase 3 model mapping — Improved with specific section names and model tier references, but the actual AGENTS.md format isn't described. The skill delegates to the README's Model Mapping section. Acceptable since the agent can read AGENTS.md directly.

Not addressed (suggestion):
8. Smoke test verification phase — Optional suggestion, omitted. The Phase 7 next-steps cover the same intent.

Verdict: All blocking and quality issues are properly resolved. Ready to merge.

opencode session  |  github run