Skip to content

Commit da5d38b

Browse files
jonathanpeterwuclaude
jonathanpeterwu
and
claude
committed
Add agent instructions and update lint log
- Add comprehensive AGENTS.md with NPM publishing, sandbox testing, and release process documentation - Update lint fix log with latest automated fixes (4 errors down from 34, warnings maintained) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 2f12552 commit da5d38b

2 files changed

Lines changed: 179 additions & 6 deletions

File tree

‎.lint-fix-log.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
[
22
{
3-
"timestamp": "2025-12-26T23:01:54.230Z",
3+
"timestamp": "2025-12-27T23:13:14.514Z",
44
"level": "info",
55
"message": "🔧 Starting auto-fix loop..."
66
},
77
{
8-
"timestamp": "2025-12-26T23:01:54.231Z",
8+
"timestamp": "2025-12-27T23:13:14.516Z",
99
"level": "info",
1010
"message": "📝 Auto-fix attempt 1/3"
1111
},
1212
{
13-
"timestamp": "2025-12-26T23:01:56.212Z",
13+
"timestamp": "2025-12-27T23:13:16.362Z",
1414
"level": "info",
15-
"message": "Found 34 errors, 76 warnings before auto-fix"
15+
"message": "Found 4 errors, 76 warnings before auto-fix"
1616
},
1717
{
18-
"timestamp": "2025-12-26T23:01:56.212Z",
18+
"timestamp": "2025-12-27T23:13:16.362Z",
1919
"level": "info",
2020
"message": "Running ESLint auto-fix..."
2121
},
2222
{
23-
"timestamp": "2025-12-26T23:01:59.647Z",
23+
"timestamp": "2025-12-27T23:13:19.551Z",
2424
"level": "success",
2525
"message": "✅ All fixable lint errors resolved! (warnings are ok for commits)"
2626
}

‎AGENTS.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# StackMemory Agent Instructions
2+
3+
## NPM Publishing Process
4+
5+
### Prerequisites
6+
1. Ensure you're logged into npm: `npm login`
7+
2. Verify login status: `npm whoami`
8+
3. If token expired, create new: `npm token create`
9+
10+
### Publishing Checklist
11+
1. **Test in Sandbox First**
12+
```bash
13+
# Create sandbox environment
14+
./scripts/create-sandbox.sh
15+
16+
# Test in sandbox
17+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh test
18+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh linear-sync
19+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh mcp-server
20+
```
21+
22+
2. **Run Tests & Lint**
23+
```bash
24+
npm test
25+
npm run lint
26+
```
27+
28+
3. **Update Version**
29+
- Update version in package.json
30+
- Create release notes in RELEASE_NOTES_v[version].md
31+
32+
4. **Commit Changes**
33+
```bash
34+
git add .
35+
git commit -m "Release v[version]: [features]"
36+
```
37+
38+
5. **Publish to NPM**
39+
```bash
40+
npm publish
41+
# If 2FA enabled, use: npm publish --otp=[code]
42+
```
43+
44+
### Common Issues & Solutions
45+
46+
#### Token Expired Error
47+
```
48+
npm error 401 Unauthorized
49+
npm error Access token expired or revoked
50+
```
51+
**Solution**: Complete npm login process
52+
1. Run `npm login`
53+
2. Complete authentication in browser
54+
3. Retry publish
55+
56+
#### 404 Not Found Error
57+
```
58+
npm error 404 Not Found - PUT
59+
```
60+
**Solution**: This usually means authentication failed
61+
1. Verify package name in package.json
62+
2. Ensure you have publish permissions
63+
3. Re-authenticate with `npm login`
64+
65+
#### OTP Required
66+
```
67+
npm error This operation requires a one-time password
68+
```
69+
**Solution**: Use `npm publish --otp=[6-digit-code]`
70+
71+
## Sandbox Environment
72+
73+
### Purpose
74+
The sandbox environment allows testing StackMemory in isolation before publishing.
75+
76+
### Creating Sandbox
77+
```bash
78+
./scripts/create-sandbox.sh
79+
```
80+
81+
This creates:
82+
- Isolated environment in `/tmp/stackmemory-sandbox/[timestamp]`
83+
- Complete npm install and build
84+
- Test project for initialization
85+
- Helper script `run-sandbox.sh`
86+
87+
### Using Sandbox
88+
```bash
89+
# Check status
90+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh status
91+
92+
# Test MCP server
93+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh mcp-server
94+
95+
# Test Linear sync
96+
export LINEAR_API_KEY="your_key"
97+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh linear-sync
98+
99+
# Run any CLI command
100+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh cli [command]
101+
102+
# Clean up
103+
/tmp/stackmemory-sandbox/[timestamp]/run-sandbox.sh clean
104+
```
105+
106+
## Feature Testing Requirements
107+
108+
### Linear Integration
109+
- Set `LINEAR_API_KEY` environment variable
110+
- Test both API key and OAuth methods
111+
- Verify task sync bidirectionally
112+
113+
### MCP Server
114+
- Test startup without errors
115+
- Verify Claude Desktop config integration
116+
- Check protocol responses
117+
118+
### Update Checker
119+
- Verify 24-hour cache mechanism
120+
- Test version comparison logic
121+
- Ensure non-intrusive notifications
122+
123+
### Progress Tracker
124+
- Check `.stackmemory/progress.json` creation
125+
- Verify session tracking
126+
- Test Linear sync status updates
127+
128+
## Release Process
129+
130+
1. **Version Bump**: Update package.json version
131+
2. **Documentation**: Create release notes
132+
3. **Sandbox Test**: Full test in isolated environment
133+
4. **Main Repo Test**: Run tests and lint
134+
5. **Commit**: Descriptive commit message
135+
6. **Publish**: npm publish with OTP if required
136+
7. **Verify**: Check npm registry for new version
137+
8. **Tag**: Create git tag for release
138+
139+
## Important Files
140+
141+
- `package.json` - Version and dependencies
142+
- `CHANGELOG.md` - User-facing changes
143+
- `RELEASE_NOTES_v*.md` - Detailed release information
144+
- `.stackmemory/progress.json` - Progress tracking
145+
- `docs/releases/` - Historical release documentation
146+
- `scripts/create-sandbox.sh` - Sandbox creation script
147+
148+
## Environment Variables
149+
150+
- `LINEAR_API_KEY` - Linear API authentication
151+
- `STACKMEMORY_ENV` - Environment mode (sandbox/production)
152+
- `STACKMEMORY_DEBUG` - Enable debug logging
153+
154+
## Commands Reference
155+
156+
### Core Commands
157+
- `stackmemory init` - Initialize in project
158+
- `stackmemory status` - Show current status
159+
- `stackmemory push/pop` - Manage context stack
160+
161+
### Integration Commands
162+
- `stackmemory linear auth` - OAuth authentication
163+
- `stackmemory linear sync` - Sync with Linear
164+
- `stackmemory linear auto-sync` - Enable auto-sync
165+
166+
### Utility Commands
167+
- `stackmemory mcp-server` - Start MCP server
168+
- `stackmemory update-check` - Check for updates
169+
- `stackmemory progress` - View progress tracking
170+
171+
### Debug Commands
172+
- `stackmemory --debug [command]` - Run with debug output
173+
- `stackmemory --version` - Show version

0 commit comments

Comments
 (0)