Skip to content

Dev #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rekabytes merged 2 commits into from
Mar 11, 2026
Merged

Dev #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f91291
fix: harden JSON.parse with try/catch, upgrade hashing md5 to sha256
rekabytes Mar 11, 2026
2bd807a
fix: add mandatory level-up reset and carry-over rule to all agents a…
rekabytes Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 194 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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 |
Expand Down Expand Up @@ -134,65 +144,89 @@ 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:
1. Shows a dry-run preview
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

Expand All @@ -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
Expand All @@ -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
```
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
Loading
Loading