From 7f91291e17c8ad2775919820e46434aa1f3fcebe Mon Sep 17 00:00:00 2001 From: Zen0space Date: Wed, 11 Mar 2026 13:10:35 +0800 Subject: [PATCH 1/2] fix: harden JSON.parse with try/catch, upgrade hashing md5 to sha256 - Wrap all JSON.parse calls in merge.js and stats.js with try/catch to give friendly error messages when xp.json is corrupted - Replace MD5 with SHA-256 in hashFile() for file change detection - Update README to reflect all 4 agents and current v1.3.2 state --- README.md | 248 ++++++++++++++++++++++++++++++++++++++++----------- src/merge.js | 19 +++- src/stats.js | 16 +++- 3 files changed, 224 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 1722d30..0a1f556 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ When you add these files to your project, OpenCode will: - Follow your coding conventions (formatting, patterns, etc.) - Write commit messages in your preferred format - Audit your code for security vulnerabilities +- Review code quality and suggest improvements +- Write and fix tests +- Write and maintain documentation - Use proper patterns for your tech stack ## Installation @@ -59,14 +62,13 @@ OpenCode automatically loads any `.opencode` folder in your project root. ## Check Your Progress -Use the `stats` command to view your agent progress: +Use the agent name as a command to view progress: ```bash -# Security agent -npx ocs-stats stats - -# Testing agent -npx ocs-stats stats testing +npx ocs-stats security # Security agent progress +npx ocs-stats testing # Testing agent progress +npx ocs-stats code-review # Code review progress +npx ocs-stats docs # Docs agent progress ``` Example output: @@ -89,23 +91,31 @@ Example output: ## Update Skills ```bash -npx ocs-stats update +npx ocs-stats update # Smart merge update +npx ocs-stats update --check # Check for updates without applying +npx ocs-stats update --force # Force fresh install ``` ## What's Included ### Agents +Switch between agents with **Tab** in OpenCode, or mention them with `@agent-name`. + | Agent | Description | |-------|-------------| -| `security` | Security expert with XP-based leveling system for auditing and fixing vulnerabilities | -| `testing` | Testing expert for unit, integration, and E2E tests with Playwright integration | +| `security` | Security expert for auditing and fixing vulnerabilities | +| `testing` | Testing expert for unit, integration, and E2E tests | +| `code-review` | Code quality reviewer — finds bugs, patterns, and improvements | +| `docs` | Documentation expert for READMEs, API docs, JSDoc, and guides | ### Skills | Skill | Description | |-------|-------------| | `commit` | Commit message conventions (type(scope): description format) | +| `code-review` | Code review patterns and best practices | +| `docs` | Documentation standards and patterns | | `memories` | Session memory for tracking work context and pending tasks | | `mobile` | Mobile development (React Native, Flutter, Swift) | | `security` | Security patterns, auth approach, and anti-patterns | @@ -134,35 +144,58 @@ Edit `.opencode/skills/commit/SKILL.md` if you use different commit formats. # Remove mobile skill if you're not building a mobile app rm -rf .opencode/skills/mobile -# Remove security agent if you don't need security audits +# Remove an agent you don't need rm -rf .opencode/agents/security rm -rf .opencode/security ``` -## Security Agent Features +## Agent XP System + +All four agents share the same XP-based leveling system. XP is only awarded after work is completed — never for planning or reviewing alone. + +### Two-Phase Workflow + +Every agent follows a strict two-step process: -The security agent includes an XP-based leveling system that tracks your progress: +- **Phase 1 — Read & Plan:** The agent analyzes your code and presents findings. No XP awarded. +- **Phase 2 — Fix/Write:** Only after you ask the agent to act, and the work is done and verified, does it earn XP. -| Level | Title | XP Required | -|-------|-------|-------------| -| 1 | Novice | 0 | -| 2 | Apprentice | 150 | +### Level Thresholds + +| Level | Title | XP to Advance | +|-------|-------|---------------| +| 1 | Novice | 150 | +| 2 | Apprentice | 300 | | 3 | Practitioner | 450 | -| 4 | Expert | 900 | -| 5 | Master | 1,500 | -| 6 | Grandmaster | 3,000 | +| 4 | Expert | 1,500 | +| 5 | Master | 3,000 | +| 6 | Grandmaster | Max level | + +## Security Agent -### XP Awards (Fix-Only System) +### XP Awards | Action | XP | |--------|-----| -| Fix critical issue | +60 XP | -| Fix high issue | +35 XP | -| Fix medium issue | +15 XP | -| Fix low issue | +10 XP | +| Fix critical vulnerability | +60 XP | +| Fix high vulnerability | +35 XP | +| Fix medium vulnerability | +15 XP | +| Fix low vulnerability | +10 XP | | Add security pattern | +30 XP | +| Document new vulnerability type | +20 XP | | Complete package audit | +75 XP | +### Level-Specific Focus + +| Level | Unlocks | +|-------|---------| +| 1 - Novice | Basic input validation, simple auth patterns, common anti-patterns | +| 2 - Apprentice | + Auth/authorization flaws, session management issues | +| 3 - Practitioner | + Data exposure risks, API security concerns | +| 4 - Expert | + Complex vulnerability chains, race conditions | +| 5 - Master | + Business logic vulnerabilities, advanced exploitation techniques | +| 6 - Grandmaster | + Custom exploit development, architecture-level security flaws | + ### Preflight Checklist Before risky operations (auth changes, DB schema, middleware), the agent: @@ -170,29 +203,30 @@ Before risky operations (auth changes, DB schema, middleware), the agent: 2. Confirms user permission 3. Documents rollback plan -## Testing Agent Features - -The testing agent helps you write tests with an XP-based leveling system: - -| Level | Title | XP Required | Focus | -|-------|-------|-------------|-------| -| 1 | Novice | 0 | Basic unit tests | -| 2 | Apprentice | 150 | Integration tests | -| 3 | Practitioner | 450 | E2E tests | -| 4 | Expert | 900 | Test patterns & mocking | -| 5 | Master | 1,500 | Full coverage strategies | -| 6 | Grandmaster | 3,000 | Testing excellence | +## Testing Agent ### XP Awards | Action | XP | |--------|-----| -| Write unit test | +10 XP | -| Write integration test | +15 XP | -| Write E2E test | +20 XP | -| Fix broken test | +10 XP | -| Add test pattern | +30 XP | -| Complete package test suite | +100 XP | +| Write passing unit test | +10 XP | +| Write passing integration test | +15 XP | +| Write passing E2E test | +20 XP | +| Fix broken/flaky test | +10 XP | +| Add new test pattern | +30 XP | +| Complete test suite (single file) | +20 XP | +| Complete test suite (package) | +100 XP | + +### Level-Specific Focus + +| Level | Unlocks | +|-------|---------| +| 1 - Novice | Basic unit tests with AAA pattern, simple function testing | +| 2 - Apprentice | + Integration tests, API testing, DB testing patterns | +| 3 - Practitioner | + E2E testing with Playwright, browser automation | +| 4 - Expert | + Advanced mocking, test utilities and factories | +| 5 - Master | + Coverage strategies, flaky test prevention, performance testing | +| 6 - Grandmaster | + Testing architecture, CI/CD integration, custom test frameworks | ### Playwright Integration @@ -202,15 +236,78 @@ When you need E2E testing: 3. Creates `opencode.json` with Playwright MCP config 4. Installs `@playwright/test` and browser binaries +## Code Review Agent + +### XP Awards + +| Action | XP | +|--------|-----| +| Fix critical issue | +60 XP | +| Fix high issue | +35 XP | +| Fix medium issue | +20 XP | +| Fix low issue | +10 XP | +| Add new pattern to skill | +30 XP | + +### Level-Specific Focus + +| Level | Unlocks | +|-------|---------| +| 1 - Novice | Basic code quality, naming conventions, simple anti-patterns | +| 2 - Apprentice | + Logic errors, edge cases, error handling, performance issues | +| 3 - Practitioner | + Design patterns, SOLID principles, code duplication | +| 4 - Expert | + Architecture concerns, scalability, complex refactoring | +| 5 - Master | + System-wide patterns, cross-cutting concerns, performance profiling | +| 6 - Grandmaster | + Strategic improvements, tech debt prioritization, team standards | + +## Docs Agent + +### XP Awards + +| Action | XP | +|--------|-----| +| Write new doc section | +20 XP | +| Improve existing docs | +15 XP | +| Add code examples | +10 XP | +| Fix doc typos/errors | +5 XP | +| Create tutorial/guide | +40 XP | +| Write API documentation | +25 XP | +| Update README | +15 XP | +| Add JSDoc comments | +10 XP | +| Create changelog entry | +10 XP | +| Add new pattern to skill | +30 XP | + +### Level-Specific Focus + +| Level | Unlocks | +|-------|---------| +| 1 - Novice | Basic README sections, code comments, getting started guides | +| 2 - Apprentice | + API docs, configuration docs, error message docs, JSDoc | +| 3 - Practitioner | + Architecture docs, design decision records, complex tutorials | +| 4 - Expert | + Contribution guidelines, release docs, migration guides | +| 5 - Master | + Comprehensive style guides, documentation architecture | +| 6 - Grandmaster | + Documentation strategy, knowledge base design, developer experience | + +## Hard Rules (All Agents) + +All agents share these rules that cannot be overridden: + +- **No `any` types** — agents will never write or suggest TypeScript's `any` type +- **No `useEffect` by default** — treated as a last resort; agents always find a cleaner approach first +- **No git commits or pushes** — agents cannot run `git commit`, `git push`, or any destructive git command + ## File Structure ``` .opencode/ ├── agents/ │ ├── security.md # Security audit agent -│ └── testing.md # Testing agent +│ ├── testing.md # Testing agent +│ ├── code-review.md # Code review agent +│ └── docs.md # Documentation agent ├── skills/ +│ ├── code-review/SKILL.md # Code review patterns │ ├── commit/SKILL.md # Commit conventions +│ ├── docs/SKILL.md # Documentation standards │ ├── memories/SKILL.md # Session memory (auto-updated) │ ├── mobile/SKILL.md # Mobile patterns (RN, Flutter, Swift) │ ├── security/SKILL.md # Security patterns @@ -219,28 +316,40 @@ When you need E2E testing: ├── security/ │ ├── xp.json # XP tracking (auto-updated) │ └── knowledge.md # Accumulated findings (auto-updated) -└── testing/ - ├── xp.json # Testing XP tracking (auto-updated) - └── knowledge.md # Testing patterns & lessons (auto-updated) +├── testing/ +│ ├── xp.json # Testing XP tracking (auto-updated) +│ └── knowledge.md # Testing patterns & lessons (auto-updated) +├── code-review/ +│ ├── xp.json # Code review XP tracking (auto-updated) +│ └── knowledge.md # Review patterns & lessons (auto-updated) +└── docs/ + ├── xp.json # Docs XP tracking (auto-updated) + └── knowledge.md # Documentation patterns & lessons (auto-updated) ``` ## For Contributors ``` opencode-skills/ -├── package.json # npm package config +├── package.json # npm package config (v1.3.2) ├── bin/cli.js # CLI entry point ├── src/ # Source files │ ├── init.js │ ├── display.js +│ ├── merge.js │ └── stats.js ├── templates/ # Files copied to user projects │ ├── agents/ │ │ ├── security.md -│ │ └── testing.md +│ │ ├── testing.md +│ │ ├── code-review.md +│ │ └── docs.md │ ├── skills/ │ ├── security/ -│ └── testing/ +│ ├── testing/ +│ ├── code-review/ +│ └── docs/ +├── CHANGELOG.md ├── README.md └── LICENSE ``` @@ -251,6 +360,24 @@ npm login npm publish ``` +## CLI Reference + +``` +ocs-stats - Install OpenCode skills and agents + +Usage: + npx ocs-stats Install to current project + npx ocs-stats --global Install globally (~/.opencode) + npx ocs-stats update Update skills (smart merge) + npx ocs-stats update --check Check for updates + npx ocs-stats update --force Force fresh install + npx ocs-stats security Show security agent progress + npx ocs-stats testing Show testing agent progress + npx ocs-stats code-review Show code-review agent progress + npx ocs-stats docs Show docs agent progress + npx ocs-stats --help Show help +``` + ## Troubleshooting ### OpenCode not finding my skills @@ -263,20 +390,33 @@ npm publish - Open the `SKILL.md` file and verify the content - Make sure the frontmatter (between `---`) is valid YAML -### Want to reset security XP? +### Stats showing zeros or MAX LEVEL incorrectly + +Make sure you're on v1.3.2 or later: +```bash +npx ocs-stats update +``` + +### Want to reset an agent's XP? Delete the tracking files and OpenCode will recreate them: ```bash +# Security rm .opencode/security/xp.json rm .opencode/security/knowledge.md -``` - -### Want to reset testing XP? -```bash +# Testing rm .opencode/testing/xp.json rm .opencode/testing/knowledge.md + +# Code Review +rm .opencode/code-review/xp.json +rm .opencode/code-review/knowledge.md + +# Docs +rm .opencode/docs/xp.json +rm .opencode/docs/knowledge.md ``` ## Contributing diff --git a/src/merge.js b/src/merge.js index 60d8783..03b7b55 100644 --- a/src/merge.js +++ b/src/merge.js @@ -31,7 +31,7 @@ const USER_PRESERVE_FIELDS = ['mode', 'tools', 'model', 'temperature', 'permissi function hashFile(filePath) { if (!fs.existsSync(filePath)) return null; const content = fs.readFileSync(filePath, 'utf-8'); - return crypto.createHash('md5').update(content).digest('hex'); + return crypto.createHash('sha256').update(content).digest('hex'); } function parseFrontmatter(content) { @@ -477,8 +477,21 @@ export async function performUpdate(targetDir, options = {}) { if (SMART_MERGE_CATEGORIES.includes(category)) { if (category === FILE_CATEGORY.XP_DATA) { - const userXp = JSON.parse(fs.readFileSync(targetPath, 'utf-8')); - const templateXp = JSON.parse(fs.readFileSync(templatePath, 'utf-8')); + let userXp, templateXp; + try { + userXp = JSON.parse(fs.readFileSync(targetPath, 'utf-8')); + } catch { + console.error(` Warning: Could not parse ${relativePath} — file may be corrupted. Skipping.`); + results.skipped.push({ path: relativePath, reason: 'corrupted JSON' }); + continue; + } + try { + templateXp = JSON.parse(fs.readFileSync(templatePath, 'utf-8')); + } catch { + console.error(` Warning: Could not parse template ${relativePath}. Skipping.`); + results.skipped.push({ path: relativePath, reason: 'corrupted template JSON' }); + continue; + } const preserveInfo = getSmartMergePreserveInfo(userXp, templateXp); diff --git a/src/stats.js b/src/stats.js index b916d43..8716fca 100644 --- a/src/stats.js +++ b/src/stats.js @@ -25,7 +25,13 @@ export function stats(category = 'security') { process.exit(1); } - const data = JSON.parse(fs.readFileSync(xpPath, 'utf-8')); + let data; + try { + data = JSON.parse(fs.readFileSync(xpPath, 'utf-8')); + } catch { + console.error(`\n Error: Could not parse ${xpPath}\n The file may be corrupted. Delete it and re-run OpenCode to reset.\n`); + process.exit(1); + } showStats(data, category); } @@ -42,7 +48,13 @@ export function displayXp(amount, reason, category = 'security') { process.exit(1); } - const data = JSON.parse(fs.readFileSync(xpPath, 'utf-8')); + let data; + try { + data = JSON.parse(fs.readFileSync(xpPath, 'utf-8')); + } catch { + console.log('No valid xp.json found — file may be corrupted.'); + process.exit(1); + } const reasonText = reason || 'XP earned'; showXpGain(parseInt(amount, 10), reasonText, data, category); } From 2bd807a7379647add66cbdd3c0cbbb3fa7e0e259 Mon Sep 17 00:00:00 2001 From: Zen0space Date: Thu, 12 Mar 2026 04:26:12 +0800 Subject: [PATCH 2/2] fix: add mandatory level-up reset and carry-over rule to all agents and skills Agents on fresh installs had no instruction to reset XP on level-up or carry overflow forward. Also corrects the Level Thresholds table in all 4 agent files from cumulative XP to per-level XP to match xp.json. --- package.json | 2 +- templates/agents/code-review.md | 30 ++++++++++++++++++++------- templates/agents/docs.md | 30 ++++++++++++++++++++------- templates/agents/security.md | 30 ++++++++++++++++++++------- templates/agents/testing.md | 30 ++++++++++++++++++++------- templates/skills/code-review/SKILL.md | 16 ++++++++++++++ templates/skills/docs/SKILL.md | 16 ++++++++++++++ templates/skills/security/SKILL.md | 16 ++++++++++++++ templates/skills/testing/SKILL.md | 16 ++++++++++++++ 9 files changed, 157 insertions(+), 29 deletions(-) diff --git a/package.json b/package.json index 9f12377..f6265d5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ocs-stats", - "version": "1.3.2", + "version": "1.3.3", "description": "OpenCode Skills - One-click installer with gamified XP stats", "type": "module", "bin": { diff --git a/templates/agents/code-review.md b/templates/agents/code-review.md index b5e936d..8882c0d 100644 --- a/templates/agents/code-review.md +++ b/templates/agents/code-review.md @@ -51,14 +51,30 @@ All mistakes are recorded in: ### Level Thresholds -| Level | Title | XP Required | -|-------|-------|-------------| -| 1 | Novice | 0 | -| 2 | Apprentice | 150 | +| Level | Title | XP to Next Level | +|-------|-------|-----------------| +| 1 | Novice | 150 | +| 2 | Apprentice | 300 | | 3 | Practitioner | 450 | -| 4 | Expert | 900 | -| 5 | Master | 1500 | -| 6 | Grandmaster | 3000 | +| 4 | Expert | 1500 | +| 5 | Master | 3000 | +| 6 | Grandmaster | — (max) | + +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/code-review/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. ## Level-Specific Focus diff --git a/templates/agents/docs.md b/templates/agents/docs.md index d5fc4e0..5812754 100644 --- a/templates/agents/docs.md +++ b/templates/agents/docs.md @@ -57,14 +57,30 @@ All mistakes are recorded in: ### Level Thresholds -| Level | Title | XP Required | -|-------|-------|-------------| -| 1 | Novice | 0 | -| 2 | Apprentice | 150 | +| Level | Title | XP to Next Level | +|-------|-------|-----------------| +| 1 | Novice | 150 | +| 2 | Apprentice | 300 | | 3 | Practitioner | 450 | -| 4 | Expert | 900 | -| 5 | Master | 1500 | -| 6 | Grandmaster | 3000 | +| 4 | Expert | 1500 | +| 5 | Master | 3000 | +| 6 | Grandmaster | — (max) | + +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/docs/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. ## Level-Specific Focus diff --git a/templates/agents/security.md b/templates/agents/security.md index 3001f48..716eb3f 100644 --- a/templates/agents/security.md +++ b/templates/agents/security.md @@ -57,14 +57,30 @@ All mistakes are recorded in: ### Level Thresholds -| Level | Title | XP Required | -|-------|-------|-------------| -| 1 | Novice | 0 | -| 2 | Apprentice | 150 | +| Level | Title | XP to Next Level | +|-------|-------|-----------------| +| 1 | Novice | 150 | +| 2 | Apprentice | 300 | | 3 | Practitioner | 450 | -| 4 | Expert | 900 | -| 5 | Master | 1500 | -| 6 | Grandmaster | 3000 | +| 4 | Expert | 1500 | +| 5 | Master | 3000 | +| 6 | Grandmaster | — (max) | + +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/security/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. ## Level-Specific Focus diff --git a/templates/agents/testing.md b/templates/agents/testing.md index 851ddec..2797b91 100644 --- a/templates/agents/testing.md +++ b/templates/agents/testing.md @@ -57,14 +57,30 @@ All mistakes are recorded in: ### Level Thresholds -| Level | Title | XP Required | Focus | -|-------|-------|-------------|-------| -| 1 | Novice | 0 | Basic unit tests | -| 2 | Apprentice | 150 | Integration tests | +| Level | Title | XP to Next Level | Focus | +|-------|-------|-----------------|-------| +| 1 | Novice | 150 | Basic unit tests | +| 2 | Apprentice | 300 | Integration tests | | 3 | Practitioner | 450 | E2E tests | -| 4 | Expert | 900 | Test patterns & mocking | -| 5 | Master | 1500 | Full coverage strategies | -| 6 | Grandmaster | 3000 | Testing excellence | +| 4 | Expert | 1500 | Test patterns & mocking | +| 5 | Master | 3000 | Full coverage strategies | +| 6 | Grandmaster | — (max) | Testing excellence | + +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/testing/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. ## Level-Specific Focus diff --git a/templates/skills/code-review/SKILL.md b/templates/skills/code-review/SKILL.md index 843698c..5713fd4 100644 --- a/templates/skills/code-review/SKILL.md +++ b/templates/skills/code-review/SKILL.md @@ -180,6 +180,22 @@ type Role = typeof ROLES[number] 8. Update XP in `.opencode/code-review/xp.json` 9. Update `knowledge.md` with new patterns or lessons +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/code-review/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. + ### XP Awards | Action | XP | diff --git a/templates/skills/docs/SKILL.md b/templates/skills/docs/SKILL.md index 748390a..f022b0d 100644 --- a/templates/skills/docs/SKILL.md +++ b/templates/skills/docs/SKILL.md @@ -262,6 +262,22 @@ code here 9. Update XP in `.opencode/docs/xp.json` 10. Update `knowledge.md` with new patterns or lessons +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/docs/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. + ### XP Awards | Action | XP | diff --git a/templates/skills/security/SKILL.md b/templates/skills/security/SKILL.md index f596b6b..46e392b 100644 --- a/templates/skills/security/SKILL.md +++ b/templates/skills/security/SKILL.md @@ -404,6 +404,22 @@ try { 8. Update XP in `.opencode/security/xp.json` 9. Update `knowledge.md` — mark issues as fixed, record new lessons +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/security/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. + ### XP Awards | Action | XP | diff --git a/templates/skills/testing/SKILL.md b/templates/skills/testing/SKILL.md index 613eea6..b68e7ec 100644 --- a/templates/skills/testing/SKILL.md +++ b/templates/skills/testing/SKILL.md @@ -490,6 +490,22 @@ vi.setSystemTime(new Date('2024-01-01')); 9. Update XP in `.opencode/testing/xp.json` 10. Update `knowledge.md` with new patterns or lessons +### Level-Up Rule (MANDATORY) + +When XP earned causes `xp` to reach or exceed `xpToNextLevel` for the current level: + +1. Subtract `xpToNextLevel` from the total XP — the remainder is the carry-over +2. Increment `level` by 1 +3. Set `title` to the new level's title +4. Set `xp` to the carry-over amount (never accumulate XP across levels) +5. Save updated `level`, `title`, and `xp` to `.opencode/testing/xp.json` + +**Example:** Level 1 (`xpToNextLevel = 150`), earn 230 XP total +→ carry-over = 230 − 150 = 80 +→ Save: `level = 2`, `title = "Apprentice"`, `xp = 80` + +**Chain level-ups:** If carry-over also meets or exceeds the next level's threshold, repeat until it doesn't. + ### XP Awards | Action | XP |