|
1 | | -# Working Directory and Access Control |
| 1 | +# StackMemory - Project Configuration |
| 2 | + |
| 3 | +## Project Structure |
| 4 | + |
| 5 | +``` |
| 6 | +src/ |
| 7 | + cli/ # CLI commands and entry point |
| 8 | + core/ # Core business logic |
| 9 | + context/ # Frame and context management |
| 10 | + database/ # Database adapters (SQLite, ParadeDB) |
| 11 | + digest/ # Digest generation |
| 12 | + query/ # Query parsing and routing |
| 13 | + integrations/ # External integrations (Linear, MCP) |
| 14 | + services/ # Business services |
| 15 | + skills/ # Claude Code skills |
| 16 | + utils/ # Shared utilities |
| 17 | +scripts/ # Build and utility scripts |
| 18 | +config/ # Configuration files |
| 19 | +docs/ # Documentation |
| 20 | +``` |
| 21 | + |
| 22 | +## Key Files |
| 23 | + |
| 24 | +- Entry: src/cli/index.ts |
| 25 | +- MCP Server: src/integrations/mcp/server.ts |
| 26 | +- Frame Manager: src/core/context/frame-manager.ts |
| 27 | +- Database: src/core/database/sqlite-adapter.ts |
| 28 | + |
| 29 | +## Detailed Guides |
| 30 | + |
| 31 | +Quick reference (agent_docs/): |
| 32 | +- linear_integration.md - Linear sync |
| 33 | +- railway_deployment.md - Deployment |
| 34 | +- mcp_server.md - MCP tools |
| 35 | +- database_storage.md - Storage |
| 36 | +- claude_hooks.md - Hooks |
| 37 | + |
| 38 | +Full documentation (docs/): |
| 39 | +- SPEC.md - Technical specification |
| 40 | +- API_REFERENCE.md - API docs |
| 41 | +- DEVELOPMENT.md - Dev guide |
| 42 | +- SETUP.md - Installation |
| 43 | + |
| 44 | +## Commands |
| 45 | + |
| 46 | +```bash |
| 47 | +npm run build # Compile TypeScript (esbuild) |
| 48 | +npm run lint # ESLint check |
| 49 | +npm run lint:fix # Auto-fix lint issues |
| 50 | +npm test # Run Vitest (watch) |
| 51 | +npm run test:run # Run tests once |
| 52 | +npm run linear:sync # Sync with Linear |
| 53 | +``` |
| 54 | + |
2 | 55 | ## Working Directory |
3 | | -- **PRIMARY**: /Users/jwu/Dev/stackmemory |
4 | | -- **ALLOWED**: All subdirectories within stackmemory project |
5 | | -- **TEMP**: /tmp for temporary operations only |
6 | | - |
7 | | -## Forbidden Directories |
8 | | -- **FORBIDDEN**: ~ (home directory root) |
9 | | -- **FORBIDDEN**: ~/.ssh (SSH keys) |
10 | | -- **FORBIDDEN**: ~/.aws (AWS credentials) |
11 | | -- **FORBIDDEN**: /etc (system configuration) |
12 | | -- **FORBIDDEN**: /usr (except /usr/bin for commands) |
13 | | -- **FORBIDDEN**: Any directory outside /Users/jwu/Dev/stackmemory without explicit permission |
14 | | -- **FORBIDDEN**: Production servers or databases |
15 | | - |
16 | | -## Docker Guidelines |
17 | | -- Always use Docker containers for testing when available |
18 | | -- Never modify host system configuration |
19 | | -- Keep containers ephemeral and stateless |
20 | | -- Clean up containers after use |
21 | | - |
22 | | -# CRITICAL: Code Validation Requirements |
23 | | -- Always run tests and lint and build after code change tasks are complete |
24 | | -- Always attempt to build and fix npm build issues after a task is complete |
25 | | -- Never fallback to mock or fake data - try to fix the actual error |
26 | | - |
27 | | -# Validation Checklist (MUST DO): |
28 | | -1. Run `npm run lint` after any code changes |
29 | | -2. Run `npm test` to verify no regressions |
30 | | -3. Run `npm run build` to ensure compilation succeeds |
31 | | -4. Actually execute the code/command to confirm it works |
32 | | -5. If any step fails, fix it before proceeding |
33 | | -- Ensure whenever we create scripts, files, test, etc to place them in the correct folder based on the repo folder structure provided in the reposiutory |
34 | | -- Always review most recent commit to load context and stackmemory.json if possible as well as recent frames to remember session whenever claude code is loaded |
35 | | -- When syncing from linear fallback to using the api script if its not working |
36 | | -- always check .env for api keys first and .zsrhc before asking for it |
37 | | -- Whenever needing to test page builds use the browser mcp or chrome claude mcp extension, if you need to do visual research do it using browser mcp |
38 | | -- Remember to run npm run linear:sync whenever a task is complete or updated |
39 | | -- Never assume or skip testing - always run lint, tests, and build after code changes |
40 | | -- Always confirm code works by running it - don't just make a guess |
41 | | -- Ask questions if you get stuck or are not 100% certain about something |
42 | | -- Tests should always pass before proceeding - fix tests first |
43 | | - |
44 | | -# Security Best Practices (CRITICAL): |
45 | | - |
46 | | -## API Keys and Secrets Management |
47 | | -1. **NEVER hardcode API keys or secrets in code files** |
48 | | - - Always use environment variables: `process.env.API_KEY` |
49 | | - - Add dotenv/config import: `import 'dotenv/config'` |
50 | | - - Check .env file first, then .zshrc/.bashrc |
51 | | - |
52 | | -2. **When fixing hardcoded secrets:** |
53 | | - - Replace with: `process.env.KEY_NAME || process.env.FALLBACK_KEY` |
54 | | - - Add error handling: |
55 | | - ```javascript |
56 | | - if (!API_KEY) { |
57 | | - console.error('❌ API_KEY environment variable not set'); |
58 | | - console.log('Please set API_KEY in your .env file or export it in your shell'); |
59 | | - process.exit(1); |
60 | | - } |
61 | | - ``` |
62 | | - - Always add `import 'dotenv/config'` at the top of scripts |
63 | | - |
64 | | -3. **GitHub Push Protection Issues:** |
65 | | - - If push is blocked due to secrets in OLD commits: |
66 | | - - Option 1: Visit GitHub URLs to allow specific secrets (if they're being removed) |
67 | | - - Option 2: Use BFG Repo-Cleaner to remove from history |
68 | | - - Option 3: Interactive rebase to edit old commits |
69 | | - - Prevention: Always check for secrets BEFORE committing with: |
70 | | - - `git diff --staged | grep -E "(api_key|token|secret|password)"` |
71 | | - - Use pre-commit hooks to scan for secrets |
72 | | - |
73 | | -4. **Environment Variable Sources (check in order):** |
74 | | - - .env file (for development) |
75 | | - - .env.local (for local overrides) |
76 | | - - ~/.zshrc or ~/.bashrc (for user-specific) |
77 | | - - Process environment (for CI/CD) |
78 | | -
|
79 | | -## Common Secret Patterns to Watch For: |
80 | | -- `lin_api_*` - Linear API keys |
81 | | -- `lin_oauth_*` - Linear OAuth tokens |
82 | | -- `sk-*` - OpenAI/Stripe keys |
83 | | -- `npm_*` - NPM tokens |
84 | | -- Any base64 encoded strings that look like tokens |
85 | | -- Hardcoded URLs with embedded credentials |
86 | | -- # Never use emojis and speak in plain developer english for comments not AI comments |
87 | | -- Ask 1-3 questions for clarity for any command given that is complex, go question by question |
88 | | -- Ask questions one at a time before moving on allow user to skip |
89 | | -- a |
90 | | -- Default to using subagents for multi step tasks if possible |
| 56 | + |
| 57 | +- PRIMARY: /Users/jwu/Dev/stackmemory |
| 58 | +- ALLOWED: All subdirectories |
| 59 | +- TEMP: /tmp for temporary operations |
| 60 | + |
| 61 | +## Validation (MUST DO) |
| 62 | + |
| 63 | +After code changes: |
| 64 | +1. `npm run lint` - fix any errors |
| 65 | +2. `npm test` - verify no regressions |
| 66 | +3. `npm run build` - ensure compilation |
| 67 | +4. Run code to verify it works |
| 68 | + |
| 69 | +Never: Assume success | Skip testing | Use mock data as fallback |
| 70 | + |
| 71 | +## Security |
| 72 | + |
| 73 | +NEVER hardcode secrets - use process.env with dotenv/config |
| 74 | + |
| 75 | +```javascript |
| 76 | +import 'dotenv/config'; |
| 77 | +const API_KEY = process.env.LINEAR_API_KEY; |
| 78 | +if (!API_KEY) { |
| 79 | + console.error('LINEAR_API_KEY not set'); |
| 80 | + process.exit(1); |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +Environment sources (check in order): |
| 85 | +1. .env file |
| 86 | +2. .env.local |
| 87 | +3. ~/.zshrc |
| 88 | +4. Process environment |
| 89 | + |
| 90 | +Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_* |
| 91 | + |
| 92 | +## Workflow |
| 93 | + |
| 94 | +- Check .env for API keys before asking |
| 95 | +- Run npm run linear:sync after task completion |
| 96 | +- Use browser MCP for visual testing |
| 97 | +- Review recent commits and stackmemory.json on session start |
| 98 | +- Use subagents for multi-step tasks |
| 99 | +- Ask 1-3 clarifying questions for complex commands (one at a time) |
0 commit comments