feat: refactor wrapper repository with templates directory

Author: apiad

.gitignore

@@ -1,3 +1,5 @@
+.opencode/
+node_modules/
 *.log
 *.env
 __pycache__

.knowledge/drafts/.gitkeep

@@ -0,0 +1,213 @@
+---
+id: audit-full-2026-03-27
+created: 2026-03-27
+modified: 2026-03-27
+type: audit
+scope: full codebase
+status: active
+---
+
+# Audit: Full Codebase — 2026-03-27
+
+## Executive Summary
+
+The opencode framework is a well-architected AI-assisted development system with a clear vision and solid fundamentals. However, it suffers from **moderate documentation drift** and **several critical configuration bugs** that could impair functionality. The core agent/command architecture is sound, but inconsistencies between documented intent and actual implementation create confusion risks.
+
+**Overall Health: 68/100** — Good foundation, needs cleanup
+
+---
+
+## Architecture Overview
+
+### Technology Stack
+| Layer         | Technology                                                 |
+| ------------- | ---------------------------------------------------------- |
+| AI Runtime    | Opencode.ai (Gemini CLI) with `@opencode-ai/plugin: 1.3.3` |
+| Build/CI      | Makefile, GitHub Actions                                   |
+| Documentation | MkDocs with Material theme                                 |
+| Scripts       | Python 3.10+ (typer, pyyaml)                               |
+| Node          | npm/yarn for plugin dependencies                           |
+
+### Directory Organization
+```
+.opencode/          → Core framework (agents, commands, bin scripts, node deps)
+.knowledge/         → Generated artifacts (notes/, plans/, log/, drafts/)
+docs/               → User-facing MkDocs documentation
+site/               → Built documentation (gitignored)
+.github/            → GitHub workflows
+.experiments/       → Subagent scratch space (gitignored)
+tests/              → Test suite (placeholder)
+```
+
+### Entry Points
+- **Primary Agents**: `analyze`, `build`, `plan`, `release` (defined in `.opencode/agents/`)
+- **Commands**: 13 commands with slash syntax (defined in `.opencode/commands/`)
+- **CLI Tool**: `.opencode/bin/note.py` — creates YAML-frontmatter notes
+- **Documentation**: `docs/` with MkDocs material theme
+
+### Core Pattern: Mode → Command → Subagent Hierarchy
+The framework enforces a disciplined workflow: agents provide context modes, commands provide structured workflows, and subagents handle specialized tasks.
+
+---
+
+## Findings
+
+### Strengths
+
+1. **Consistent YAML Frontmatter Standard** — Agent and command definitions follow a well-structured frontmatter pattern with consistent fields (`description`, `mode`, `permission`)
+
+2. **Phase-Based Workflows** — Commands like `research.md`, `plan.md`, and `audit.md` define clear phase-based workflows with explicit constraints
+
+3. **Excellent Output Templates** — `investigator.md` and `audit.md` provide comprehensive output templates with examples
+
+4. **Structured Knowledge Storage** — The `.knowledge/` directory with `notes/`, `plans/`, `log/`, `drafts/` separation is well-designed
+
+5. **No Cyclomatic Complexity Issues** — All files are appropriately sized; no hotspots detected
+
+6. **Modern Python Script** — `note.py` uses type hints, pathlib, and modern patterns (inline deps)
+
+7. **Clear Separation of Concerns** — Agents, commands, and subagents have distinct responsibilities
+
+8. **Test-Commit-Revert Discipline** — The framework enforces TCR for build operations with clear guidance
+
+### Concerns
+
+| Area                        | Severity     | Description                                                                                                 | Location                                                                   | Recommendation                                               |
+| --------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Permission Bug              | **Critical** | Typo in `plan.md`: `.knowledege/plans/*` instead of `.knowledge/plans/*`                                    | `.opencode/agents/plan.md:8`                                               | Fix typo immediately                                         |
+| Missing Subagent Permission | **High**     | `investigator` subagent used in plan.md content but not declared in frontmatter `task:` permissions         | `.opencode/agents/plan.md`                                                 | Add `investigator` to task permissions                       |
+| Documentation Drift         | **High**     | 8+ documented commands not implemented; 5+ agent names in docs don't exist                                  | `docs/design.md`, `docs/user-guide.md`, `README.md`                        | Audit and align docs with actual implementations             |
+| YAML Frontmatter Violation  | **High**     | 4 of 7 checked knowledge files don't follow the standard format (missing `id`, `created`, `type`, `status`) | `.knowledge/notes/*.md`, `.knowledge/plans/*.md`, `.knowledge/drafts/*.md` | Add frontmatter to all knowledge files                       |
+| Makefile Incomplete         | **High**     | `lint` target is empty but `all` depends on it; `format` target declared but undefined                      | `makefile`                                                                 | Implement or remove dependencies                             |
+| Gitignore Incomplete        | **Medium**   | `.opencode/node_modules/` and `.opencode/bun.lock` not gitignored                                           | `.gitignore`                                                               | Add these patterns                                           |
+| Missing `mode` Field        | **Medium**   | `build.md` missing `mode: primary` in frontmatter unlike other agents                                       | `.opencode/agents/build.md`                                                | Add consistent frontmatter                                   |
+| Unregistered Subagent       | **Medium**   | `general` subagent referenced in `build.md` but not in AGENTS.md registry                                   | `.opencode/agents/build.md:25`                                             | Register or remove `general`                                 |
+| Empty Test Suite            | **Medium**   | `make test` does nothing; placeholder test always passes                                                    | `tests/test_placeholder.py`                                                | Implement actual tests or document TCR as primary validation |
+| Race Condition              | **Low**      | `note.py` checks file existence then writes without atomic operation                                        | `.opencode/bin/note.py:71-78`                                              | Use `Path.write_text` directly with error handling           |
+
+### Technical Debt
+
+| Item                   | Severity | Location                       | Description                                                                          |
+| ---------------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------ |
+| Permission typo        | High     | `.opencode/agents/plan.md:8`   | `.knowledege/plans/*` → should be `.knowledge/plans/*`                               |
+| Documentation drift    | High     | `docs/design.md:8-28`          | References non-existent agents: `query`, `research`, `brainstorm`, `write`, `review` |
+| Missing commands       | Medium   | `README.md`, `docs/*.md`       | `/brainstorm`, `/document`, `/cron`, `/learn` documented but not implemented         |
+| Frontmatter violations | Medium   | `.knowledge/drafts/*.md`       | 4+ knowledge files lack required YAML frontmatter                                    |
+| Gitignore gaps         | Medium   | `.gitignore`                   | `node_modules/`, `bun.lock`, `*.pyc` not ignored                                     |
+| Unregistered subagent  | Low      | `.opencode/agents/build.md:25` | `general` subagent used but not in AGENTS.md registry                                |
+| Typo in README         | Low      | `README.md:49`                 | "oppinionanted" → "opinionated"                                                      |
+| Typo in note.py        | Low      | `.opencode/bin/note.py:81`     | "NOT being saved" → "NOT been saved"                                                 |
+
+### Minor Issues (Actionable but Low Priority)
+
+1. **Outdated path references** in `docs/develop.md` (lines 117, 130) — references old paths like `plans/`, `research/` instead of `.knowledge/plans/`, etc.
+2. **Commit scope confusion** — `docs(research)` scope unclear; should align with directory structure
+3. **README references old commands** — Still mentions `gemini /onboard` instead of `opencode /onboard`
+4. **MkDocs serve dependencies** — `makefile` doesn't declare `mkdocs` as a dependency
+
+---
+
+## Recommendations
+
+### Priority 1: Fix Critical Bugs
+1. Fix typo in `.opencode/agents/plan.md` line 8: `.knowledege/plans/*` → `.knowledge/plans/*`
+2. Add `investigator` to `plan.md`'s `task:` permissions block
+
+### Priority 2: Align Documentation with Implementation
+1. Audit `README.md` and remove references to unimplemented commands (`/brainstorm`, `/document`, `/cron`, `/learn`)
+2. Update `docs/design.md` and `docs/user-guide.md` to reference actual agent names (`analyze`, `build`, `plan`, `release` instead of `query`, `research`, `brainstorm`)
+3. Update `docs/develop.md` path references to use `.knowledge/` prefixes
+
+### Priority 3: Enforce YAML Frontmatter Standard
+1. Add frontmatter to all files in `.knowledge/drafts/` and any `.knowledge/plans/` files missing it
+2. Standardize on the format: `id`, `created`, `modified`, `type`, `status` (plus optional fields)
+
+### Priority 4: Complete Makefile Implementation
+1. Either implement `lint` target (e.g., markdown lint, Python lint) or remove it from `all` dependencies
+2. Either implement `format` target or remove from `.PHONY`
+3. Add `install-hooks` target referenced in `docs/develop.md`
+4. Add standard `help` target for self-documenting makefile
+
+### Priority 5: Improve Git Hygiene
+1. Add to `.gitignore`:
+   ```
+   .opencode/node_modules/
+   .opencode/bun.lock
+   *.pyc
+   .pytest_cache/
+   ```
+2. Consider adding a `.gitignore` entry for IDE files (`.idea/`, `*.swp`)
+
+### Priority 6: Registry Alignment
+1. Register `general` subagent in AGENTS.md's Subagent Registry if it's intentionally used
+2. Audit command files vs AGENTS.md command registry listing
+3. Add `mode: primary` to `build.md` frontmatter for consistency
+
+### Priority 7: Test Coverage
+1. Document that TCR is the primary validation mechanism (already in `docs/develop.md`)
+2. If keeping unit tests, implement actual test cases in `tests/test_placeholder.py`
+3. Consider adding integration tests for `note.py`
+
+---
+
+## Compliance Scores
+
+| Category              | Score | Notes                                            |
+| --------------------- | ----- | ------------------------------------------------ |
+| Architecture Patterns | 75%   | Core patterns solid; permission system has bugs  |
+| Code Quality          | 85%   | No complexity hotspots; minor issues in note.py  |
+| Standards Compliance  | 65%   | YAML frontmatter violations; incomplete makefile |
+| Technical Debt        | 60%   | Critical bugs + documentation drift              |
+
+**Overall: 68%** — Solid foundation with significant cleanup needed
+
+---
+
+## Appendix: Files Analyzed
+
+### Agents (9 files)
+- `.opencode/agents/analyze.md`
+- `.opencode/agents/build.md`
+- `.opencode/agents/plan.md`
+- `.opencode/agents/release.md`
+- `.opencode/agents/scout.md`
+- `.opencode/agents/investigator.md`
+- `.opencode/agents/critic.md`
+- `.opencode/agents/tester.md`
+- `.opencode/agents/drafter.md`
+
+### Commands (13 files)
+- `.opencode/commands/research.md`
+- `.opencode/commands/plan.md`
+- `.opencode/commands/onboard.md`
+- `.opencode/commands/audit.md`
+- `.opencode/commands/build.md`
+- `.opencode/commands/fix.md`
+- `.opencode/commands/draft.md`
+- `.opencode/commands/commit.md`
+- `.opencode/commands/publish.md`
+- `.opencode/commands/investigate.md`
+- `.opencode/commands/note.md`
+- `.opencode/commands/todo.md`
+- `.opencode/commands/todowrite.md`
+
+### Scripts & Config
+- `.opencode/bin/note.py`
+- `opencode.json`
+- `.opencode/package.json`
+- `makefile`
+- `mkdocs.yml`
+- `.gitignore`
+
+### Documentation
+- `README.md`
+- `docs/develop.md`
+- `docs/design.md`
+- `docs/user-guide.md`
+- `AGENTS.md`
+
+### Knowledge Files
+- `.knowledge/notes/*.md` (3 files)
+- `.knowledge/plans/*.md` (4 files)
+- `.knowledge/drafts/*.md` (2 files)
+- `.knowledge/log/*.md` (1 file)

.knowledge/log/.gitkeep

@@ -7,10 +7,10 @@ status: active
 expires: 2026-04-03
 phases:
   - name: Create opencode-core Repository
-    done: false
+    done: true
     goal: Extract framework components into standalone repository
   - name: Rename Current Repository
-    done: false
+    done: true
     goal: Rename starter to opencode for clarity
   - name: Implement Dual-Mode Installer
     done: false
@@ -270,9 +270,8 @@ cd project && git submodule update --init --recursive
 
 ## Related
 
-- **Current Repository:** `https://github.com/apiad/starter.git`
-- **New Framework Repository:** `https://github.com/apiad/opencode-core.git` (to be created)
-- **Renamed Repository:** `https://github.com/apiad/opencode.git` (after rename)
+- **Framework Repository:** `https://github.com/apiad/opencode-core.git` ✓
+- **Wrapper Repository:** `https://github.com/apiad/opencode.git` ✓ (renamed from starter)
 
 ---