Skip to content

Commit 678c98a

Browse files
deiviudsdeiviuds
committed
docs: overhaul documentation and project metadata
Expand README with comprehensive guides, FAQ, and troubleshooting. Update command help files with detailed usage and examples. Add LICENSE, CONTRIBUTING.md, and CHANGELOG.md. Update package.json metadata, repository links, and keywords. Add project banner and GitHub configuration.
1 parent 092e789 commit 678c98a

12 files changed

Lines changed: 963 additions & 65 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18, 20, 22]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Setup Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
cache: 'npm'
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Build
30+
run: npm run build
31+
32+
- name: Type check
33+
run: npm run typecheck
34+
35+
- name: Test
36+
run: npm test
37+
38+
# Verify the plugin structure is correct
39+
verify-plugin:
40+
runs-on: ubuntu-latest
41+
needs: build
42+
43+
steps:
44+
- uses: actions/checkout@v4
45+
46+
- name: Setup Node.js
47+
uses: actions/setup-node@v4
48+
with:
49+
node-version: 20
50+
cache: 'npm'
51+
52+
- name: Install dependencies
53+
run: npm ci
54+
55+
- name: Build
56+
run: npm run build
57+
58+
- name: Verify plugin structure
59+
run: |
60+
echo "Checking plugin structure..."
61+
test -d dist || (echo "Missing dist directory" && exit 1)
62+
test -f dist/index.js || (echo "Missing dist/index.js" && exit 1)
63+
test -f dist/index.d.ts || (echo "Missing dist/index.d.ts" && exit 1)
64+
test -f dist/plugin.js || (echo "Missing dist/plugin.js" && exit 1)
65+
test -d .opencode || (echo "Missing .opencode directory" && exit 1)
66+
test -d .opencode/commands || (echo "Missing .opencode/commands" && exit 1)
67+
test -d .opencode/skills || (echo "Missing .opencode/skills" && exit 1)
68+
test -f opencodeBrain-banner.png || (echo "Missing banner image" && exit 1)
69+
echo "Plugin structure verified!"

‎.github/workflows/release.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
permissions:
13+
contents: write
14+
id-token: write
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: 20
23+
cache: 'npm'
24+
registry-url: 'https://registry.npmjs.org'
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Build
30+
run: npm run build
31+
32+
- name: Run tests
33+
run: npm test
34+
35+
- name: Verify plugin structure
36+
run: |
37+
test -f dist/index.js
38+
test -f dist/plugin.js
39+
test -d .opencode/commands
40+
test -d .opencode/skills
41+
test -f opencodeBrain-banner.png
42+
43+
- name: Publish to npm
44+
run: npm publish --provenance --access public
45+
env:
46+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
47+
48+
- name: Create GitHub Release
49+
uses: softprops/action-gh-release@v1
50+
with:
51+
generate_release_notes: true
52+
body: |
53+
## Installation
54+
55+
```bash
56+
npm install opencode-brain
57+
```
58+
59+
Add to your `opencode.json`:
60+
```json
61+
{
62+
"plugin": ["opencode-brain"]
63+
}
64+
```
65+
66+
## What's New
67+
68+
See [CHANGELOG.md](https://github.com/deiviuds/opencode-brain/blob/main/CHANGELOG.md) for details.
69+
70+
## Documentation
71+
72+
- [README](https://github.com/deiviuds/opencode-brain#readme)
73+
- [Contributing Guide](https://github.com/deiviuds/opencode-brain/blob/main/CONTRIBUTING.md)
74+
75+
## Cross-Tool Compatibility
76+
77+
This plugin is 100% compatible with [claude-brain](https://github.com/memvid/claude-brain).
78+
Both tools share the same `.claude/mind.mv2` file.
79+
env:
80+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.opencode/commands/ask.md‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,64 @@
22
description: Ask questions about past work and decisions
33
---
44

5-
Ask the mind: $ARGUMENTS
5+
# Mind Ask
66

7-
Use the mind_ask tool with the question provided.
7+
Ask natural language questions about your project's history and get answers based on stored memories.
8+
9+
## Usage
10+
11+
Use the mind_ask tool with question: $ARGUMENTS
12+
13+
## How it Works
14+
15+
- Finds relevant memories using context search
16+
- Synthesizes an answer from multiple observations
17+
- Provides sources and timestamps
18+
19+
## Examples
20+
21+
**Ask about decisions:**
22+
```
23+
/mind:ask "Why did we switch from REST to GraphQL?"
24+
```
25+
26+
**Ask about implementations:**
27+
```
28+
/mind:ask "How did we implement authentication?"
29+
```
30+
31+
**Ask about problems:**
32+
```
33+
/mind:ask "What was the database connection issue?"
34+
```
35+
36+
**Ask about recent work:**
37+
```
38+
/mind:ask "What features were added this week?"
39+
```
40+
41+
## Output Format
42+
43+
Provides:
44+
- **Natural language answer** based on observations
45+
- **Context** from relevant memories
46+
- **Timestamps** showing when events occurred
47+
- **Source attribution** (opencode vs claude-code)
48+
49+
## Tips
50+
51+
- Use complete questions for best results
52+
- More specific questions get better answers
53+
- Combines information from multiple observations
54+
- Works with both opencode and claude-brain memories
55+
56+
## Difference from Search
57+
58+
- **mind_search**: Returns raw observations with scores
59+
- **mind_ask**: Returns synthesized answer from multiple sources
60+
61+
## See Also
62+
63+
- `/mind:search` - Find specific observations
64+
- `/mind:recent` - View what happened lately
65+
- `/mind:stats` - View memory statistics

‎.opencode/commands/recent.md‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,88 @@
22
description: Show recent memory timeline
33
---
44

5-
Use the mind_timeline tool to show recent memories.
5+
# Mind Recent
66

7-
$ARGUMENTS
7+
View recent observations in chronological order to see what work has been done lately.
8+
9+
## Usage
10+
11+
Use the mind_timeline tool to show recent memories: $ARGUMENTS
12+
13+
**Optional argument:** Number of observations to show (default: 20)
14+
15+
## Examples
16+
17+
**Show last 20 observations (default):**
18+
```
19+
/mind:recent
20+
```
21+
22+
**Show last 5 observations:**
23+
```
24+
/mind:recent 5
25+
```
26+
27+
**Show last 50 observations:**
28+
```
29+
/mind:recent 50
30+
```
31+
32+
## Output Format
33+
34+
Displays observations in reverse chronological order (newest first):
35+
36+
```
37+
📅 Recent Observations (last 5):
38+
39+
1. 5 minutes ago | [feature] Added user authentication endpoints
40+
Implemented JWT-based auth with refresh tokens
41+
Source: opencode
42+
43+
2. 15 minutes ago | [discovery] Found existing auth middleware
44+
Located reusable auth middleware in src/middleware/
45+
Source: opencode
46+
47+
3. 1 hour ago | [problem] TypeScript errors in auth service
48+
Missing types for User interface
49+
Source: opencode
50+
```
51+
52+
## What You'll See
53+
54+
Each observation shows:
55+
- **Timestamp** (relative: "5 minutes ago")
56+
- **Type** (discovery, problem, solution, feature, etc.)
57+
- **Summary** (one-line description)
58+
- **Content** (detailed information)
59+
- **Source** (opencode or claude-code)
60+
61+
## When to Use
62+
63+
- **Daily standup** - Review what you worked on
64+
- **Context refresh** - Remember where you left off
65+
- **Team handoff** - Share what was done
66+
- **Progress tracking** - See recent accomplishments
67+
68+
## Tips
69+
70+
- Use smaller limits (5-10) for quick overview
71+
- Use larger limits (50+) for detailed review
72+
- Timeline includes both opencode and claude-code observations
73+
- Observations are captured automatically from tool usage
74+
75+
## Observation Types
76+
77+
- **discovery** - New information found
78+
- **decision** - Choices made
79+
- **problem** - Errors encountered
80+
- **solution** - Fixes implemented
81+
- **feature** - Features added
82+
- **refactor** - Code refactored
83+
- **bugfix** - Bugs fixed
84+
85+
## See Also
86+
87+
- `/mind:search` - Find specific observations
88+
- `/mind:ask` - Ask questions about your work
89+
- `/mind:stats` - View memory statistics

‎.opencode/commands/search.md‎

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,61 @@
22
description: Search memories for relevant context (shared with Claude Code)
33
---
44

5-
Search the mind memory for: $ARGUMENTS
5+
# Mind Search
66

7-
Use the mind_search tool with the query provided.
7+
Search through stored observations and memories using fast lexical search.
8+
9+
## Usage
10+
11+
Use the mind_search tool with query: $ARGUMENTS
12+
13+
## What it Searches
14+
15+
- All observations captured from tool usage
16+
- Session summaries
17+
- Both opencode and claude-code memories (if using both tools)
18+
19+
## Examples
20+
21+
**Search for errors:**
22+
```
23+
/mind:search "authentication error"
24+
```
25+
26+
**Search for specific files:**
27+
```
28+
/mind:search "database.ts"
29+
```
30+
31+
**Search for decisions:**
32+
```
33+
/mind:search "why did we choose"
34+
```
35+
36+
**Search for recent changes:**
37+
```
38+
/mind:search "refactored API endpoints"
39+
```
40+
41+
## Output Format
42+
43+
Results include:
44+
- **Observation type** (discovery, problem, solution, etc.)
45+
- **Summary** text
46+
- **Relevance score** (0-1, higher is more relevant)
47+
- **Timestamp** (relative, e.g., "2h ago")
48+
- **Source** (opencode or claude-code)
49+
- **Content snippet**
50+
51+
## Tips
52+
53+
- Use specific terms for better results
54+
- Search works on both title and content
55+
- Results are ranked by relevance
56+
- Limited to 10 results by default
57+
58+
## See Also
59+
60+
- `/mind:ask` - Ask natural language questions
61+
- `/mind:recent` - View chronological timeline
62+
- `/mind:stats` - View memory statistics

0 commit comments

Comments
 (0)