Skip to content

Commit b40a572

Browse files
author
StackMemory Bot (CLI)
committed
docs(specs): add iterative spec documents for StackMemory
Complete 4-doc spec chain: ONE_PAGER, DEV_SPEC, PROMPT_PLAN, AGENTS.md with real StackMemory project content. Stages A-D marked complete, E-G are the roadmap for team collaboration, hosted service, and polish.
1 parent fca84e6 commit b40a572

4 files changed

Lines changed: 253 additions & 0 deletions

File tree

‎docs/specs/AGENTS.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# StackMemory — AGENTS.md
2+
3+
> Generated from ONE_PAGER.md, DEV_SPEC.md, PROMPT_PLAN.md
4+
5+
## Repository Structure
6+
```
7+
src/
8+
cli/ → CLI entry point + commands (commander.js)
9+
core/ → Business logic (frames, database, query, retrieval)
10+
integrations/ → External services (Linear, MCP, Claude Code, Ralph)
11+
skills/ → Claude Code skills (spec, linear-run, orchestrator)
12+
features/ → Feature modules (tasks, TUI)
13+
utils/ → Shared utilities
14+
packages/ → Workspace packages (linear-extension)
15+
.claude/ → Claude Code config (hooks, skills, settings)
16+
docs/specs/ → Iterative spec documents
17+
```
18+
19+
## Agent Responsibilities
20+
21+
### When editing `src/core/`
22+
- Frame operations are the foundation — test thoroughly
23+
- FrameManager, DualStackManager, ContextRetriever are hot paths
24+
- SQLiteAdapter uses better-sqlite3 (synchronous API, not async)
25+
- Always use `.js` extensions on relative ESM imports
26+
27+
### When editing `src/skills/`
28+
- Skills return `SkillResult { success, message, data?, action? }`
29+
- Register new skills in `ClaudeSkillsManager.executeSkill()` switch
30+
- Add to `getAvailableSkills()` and `getSkillHelp()` too
31+
- RecursiveAgentOrchestrator has 8 subagent types — don't add without reason
32+
33+
### When editing `src/cli/`
34+
- Feature-flagged commands use async `import()` collected in `lazyCommands[]`
35+
- All lazy commands must resolve before `program.parse()`
36+
- Use `ora` for spinners, `chalk` for colors
37+
38+
### When editing `src/integrations/`
39+
- Linear: always check for `LINEAR_API_KEY` before API calls
40+
- MCP: tools must follow `@modelcontextprotocol/sdk` patterns
41+
- Claude Code: agent bridge maps oracle/worker/reviewer types
42+
43+
## Guardrails
44+
- **Never** commit secrets (`.env`, API keys, tokens)
45+
- **Never** use `--no-verify` on git operations
46+
- **Never** use `jest` — this project uses `vitest`
47+
- **Never** skip `.js` extensions on relative imports (ESM requirement)
48+
- **Always** run `npm run lint && npm run test:run && npm run build` before pushing
49+
- **Always** return `undefined` over throwing exceptions
50+
- **Always** log + continue rather than crash
51+
52+
## Testing
53+
- Framework: Vitest (not Jest)
54+
- Run: `npm run test:run` (single pass) or `npm test` (watch mode)
55+
- Location: `src/**/__tests__/*.test.ts` or colocated `*.test.ts`
56+
- Target: 498 tests, all passing, ~17s
57+
- New features require tests — no untested code paths
58+
59+
## When to Ask the User
60+
- Before creating new subagent types in RecursiveAgentOrchestrator
61+
- Before modifying database schema (migrations needed)
62+
- Before changing feature flag defaults
63+
- Before adding new npm dependencies
64+
- Before modifying `.claude/hooks/` behavior
65+
- When a test fails and the fix isn't obvious

‎docs/specs/DEV_SPEC.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# StackMemory — Development Specification
2+
3+
> Generated from ONE_PAGER.md
4+
5+
## Architecture
6+
7+
```
8+
┌──────────────────────────────────────────────────┐
9+
│ CLI (commander) MCP Server (SSE) │
10+
├──────────────────────────────────────────────────┤
11+
│ Skills Layer │
12+
│ ├─ SpecGeneratorSkill (4-doc chain) │
13+
│ ├─ LinearTaskRunner (task → RLM → Linear) │
14+
│ ├─ ClaudeSkillsManager (skill router) │
15+
│ └─ UnifiedRLMOrchestrator (RLM + skills) │
16+
├──────────────────────────────────────────────────┤
17+
│ Core │
18+
│ ├─ FrameManager (push/pop/query) │
19+
│ ├─ DualStackManager (hot + cold stacks) │
20+
│ ├─ ContextRetriever (semantic search) │
21+
│ ├─ RecursiveAgentOrchestrator (8 subagents) │
22+
│ └─ ParallelExecutor (concurrent tasks) │
23+
├──────────────────────────────────────────────────┤
24+
│ Storage │
25+
│ ├─ SQLiteAdapter (local, better-sqlite3)│
26+
│ └─ ParadeDB adapter (hosted, optional) │
27+
├──────────────────────────────────────────────────┤
28+
│ Integrations │
29+
│ ├─ Linear (OAuth + webhook) │
30+
│ ├─ Claude Code (agent bridge + hooks) │
31+
│ └─ Ralph (swarm coordinator) │
32+
└──────────────────────────────────────────────────┘
33+
```
34+
35+
## Tech Stack
36+
- **Language**: TypeScript (strict mode, ESM with .js extensions)
37+
- **Runtime**: Node.js 20+
38+
- **Build**: esbuild (fast, single-pass)
39+
- **Test**: Vitest (498 tests, ~17s)
40+
- **Lint**: ESLint + Prettier
41+
- **Database**: better-sqlite3 (local), ParadeDB (hosted)
42+
- **CLI**: Commander.js
43+
- **MCP**: Custom SSE server (@modelcontextprotocol/sdk)
44+
45+
## API Contracts
46+
47+
### MCP Tools
48+
- `stackmemory_push_frame` — Push context frame onto stack
49+
- `stackmemory_pop_frame` — Pop and return top frame
50+
- `stackmemory_query` — Semantic search across frames
51+
- `stackmemory_capture` — Snapshot current state for handoff
52+
- `stackmemory_restore` — Rehydrate from captured state
53+
54+
### CLI Commands
55+
- `stackmemory capture` / `restore` — Session handoff
56+
- `stackmemory skills spec <cmd>` — Spec document generation
57+
- `stackmemory skills linear-run <cmd>` — Linear task execution
58+
- `stackmemory ralph linear <cmd>` — Ralph-Linear bridge
59+
60+
### Internal Interfaces
61+
- `SkillContext` — Shared context passed to all skills
62+
- `SkillResult` — Uniform { success, message, data?, action? } return
63+
- `SubagentConfig` — Model, tokens, temperature, systemPrompt, capabilities
64+
- `TaskNode` — Recursive task tree with dependencies and status
65+
66+
## Data Models
67+
68+
### Frame
69+
```typescript
70+
{ id, projectId, type, topic, summary, content, metadata,
71+
parentId, status, score, createdAt, updatedAt }
72+
```
73+
74+
### LinearTask (synced)
75+
```typescript
76+
{ id, identifier, title, description, status, priority,
77+
labels[], team, assignee, url }
78+
```
79+
80+
## Auth
81+
- Local: no auth (single-user SQLite)
82+
- Hosted: JWT via `stackmemory login`
83+
- Linear: OAuth2 flow or `LINEAR_API_KEY` env var
84+
- Claude: `ANTHROPIC_API_KEY` env var
85+
86+
## Error Handling
87+
- Return `undefined` over throwing (per CLAUDE.md convention)
88+
- Log + continue over crash
89+
- Skills return `{ success: false, message }` on failure
90+
- Hooks silently fail to not block Claude
91+
92+
## Deploy
93+
- npm package: `@stackmemoryai/stackmemory`
94+
- Binary: `stackmemory` (global install)
95+
- Feature flags: `STACKMEMORY_SKILLS`, `STACKMEMORY_RALPH`, etc.
96+
- Auto-update check on CLI startup

‎docs/specs/ONE_PAGER.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# StackMemory — One-Pager
2+
3+
## Problem
4+
AI coding agents (Claude Code, Cursor, Copilot) lose all context between sessions. Developers repeat themselves, decisions get lost, and handoffs between agents or team members are painful. Current tools treat chat as linear logs — there's no structured memory layer.
5+
6+
## Audience
7+
- Solo developers using AI coding assistants daily
8+
- Engineering teams (2-20) collaborating with AI agents across sessions
9+
- AI-first startups where agents do 50%+ of the coding
10+
11+
## Platform
12+
CLI + MCP server — runs locally alongside Claude Code / VS Code. Optional hosted sync for teams.
13+
14+
## Core Flow
15+
1. Developer works with Claude Code — StackMemory auto-captures context as frames on a call stack
16+
2. Session ends — `stackmemory capture` commits state + generates handoff prompt
17+
3. New session starts — `stackmemory restore` rehydrates full context
18+
4. Team member picks up — frames show decisions, progress, blockers with full provenance
19+
5. Ralph (RLM orchestrator) decomposes complex tasks into parallel subagent execution
20+
21+
## MVP Features
22+
- [x] Frame-based context management (push/pop/query)
23+
- [x] Session capture and restore with handoff prompts
24+
- [x] SQLite local storage with dual-stack manager
25+
- [x] MCP server for Claude Desktop integration
26+
- [x] Linear task sync (bidirectional)
27+
- [x] Recursive Language Model (RLM) orchestrator with 8 subagent types
28+
- [x] Claude Code skills system (/spec, /linear-run, checkpoint, dig)
29+
- [ ] Team collaboration with shared frame stacks
30+
- [ ] Hosted sync service (Railway/Supabase)
31+
- [ ] Browser extension for context capture
32+
33+
## Non-Goals
34+
- Not a replacement for git — complements version control
35+
- Not a chat UI — headless memory layer for existing tools
36+
- Not a project management tool — integrates with Linear, not replaces it
37+
38+
## Metrics
39+
- Session restoration accuracy (% of context successfully rehydrated)
40+
- Handoff quality score (does the next agent/human have sufficient context?)
41+
- Token savings (fewer repeated explanations across sessions)
42+
- Task completion rate via Ralph orchestrator

‎docs/specs/PROMPT_PLAN.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# StackMemory — Prompt Plan
2+
3+
> Generated from ONE_PAGER.md, DEV_SPEC.md
4+
5+
## Stage A: Foundation (Complete)
6+
- [x] Initialize repository and tooling
7+
- [x] Configure CI/CD pipeline (lint-staged + pre-commit)
8+
- [x] Set up development environment (esbuild, vitest)
9+
- [x] Define database schema (SQLite frames table)
10+
- [x] Implement FrameManager (push/pop/query)
11+
- [x] Implement DualStackManager (hot + cold stacks)
12+
13+
## Stage B: Core Features (Complete)
14+
- [x] Session capture and restore
15+
- [x] Handoff prompt generation
16+
- [x] Context retrieval with semantic search
17+
- [x] CLI commands (capture, restore, status, context)
18+
- [x] MCP server with SSE transport
19+
20+
## Stage C: Integrations (Complete)
21+
- [x] Linear OAuth + task sync
22+
- [x] Linear webhook handler
23+
- [x] Claude Code agent bridge
24+
- [x] Claude Code hooks system
25+
26+
## Stage D: Skills & Orchestration (Complete)
27+
- [x] RecursiveAgentOrchestrator with 8 subagent types
28+
- [x] ClaudeSkillsManager with skill routing
29+
- [x] SpecGeneratorSkill (4-doc chain)
30+
- [x] LinearTaskRunner (task → RLM → Linear)
31+
- [x] Agent prompt consolidation (structured templates, latest models)
32+
- [x] Workflow integration (hooks, skill-rules, CLI)
33+
34+
## Stage E: Team Collaboration (Next)
35+
- [ ] Shared frame stacks across team members
36+
- [ ] Conflict resolution for concurrent frame edits
37+
- [ ] Team activity feed and notifications
38+
- [ ] Role-based access control for frames
39+
40+
## Stage F: Hosted Service
41+
- [ ] Railway/Supabase hosted database
42+
- [ ] User signup and JWT auth
43+
- [ ] Remote MCP server (HTTP/SSE)
44+
- [ ] Cross-device sync
45+
46+
## Stage G: Polish & Scale
47+
- [ ] Browser extension for context capture
48+
- [ ] Performance optimization (frame indexing, lazy loading)
49+
- [ ] Telemetry and usage analytics
50+
- [ ] Plugin marketplace for custom skills

0 commit comments

Comments
 (0)