Skip to content

Commit b205252

Browse files
author
Marvin Zhang
committed
Merge branch 'develop'
2 parents 497b9af + 6ab1136 commit b205252

File tree

3 files changed

+238
-67
lines changed

3 files changed

+238
-67
lines changed

‎.vscode/mcp.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@
55
"args": ["@playwright/mcp@latest", "--isolated"],
66
"type": "stdio"
77
},
8-
"lean-spec": {
8+
"leanspec": {
99
"type": "stdio",
1010
"command": "npx",
11-
"args": ["lean-spec", "mcp"],
12-
"cwd": "${workspaceFolder}",
13-
"env": {}
11+
"args": ["@leanspec/mcp@0.2.9"],
12+
"env": {},
13+
"cwd": "${workspaceFolder}"
1414
}
1515
},
1616
"inputs": [

‎AGENTS.md‎

Lines changed: 80 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -37,94 +37,111 @@
3737

3838
---
3939

40-
## 📋 LeanSpec - Lightweight Specification Management
40+
## 📋 LeanSpec - Specification Management
4141

4242
**Philosophy**: Lightweight spec methodology for AI-powered development. Clarity over documentation.
4343

44-
### Core Principles
44+
### 🚨 CRITICAL: Before ANY Task
4545

46-
1. **Read README.md first** - Understand project context before starting
47-
2. **Check specs/** - Review existing specs to avoid duplicate work
48-
3. **Keep it minimal** - If it doesn't add clarity, cut it
49-
4. **Stay in sync** - Specs evolve with implementation
46+
**STOP and check these first:**
5047

51-
### When to Create a Spec
52-
53-
**Create specs for:**
54-
55-
- Features requiring design/planning (>2 days work)
56-
- Features that affect multiple parts of the system
57-
- Architectural decisions affecting multiple components
58-
- Breaking changes or significant refactors
59-
- Design decisions needing team alignment
60-
- Complex features benefiting from upfront thinking
61-
62-
**Skip specs for:**
63-
64-
- Bug fixes
65-
- Trivial changes
66-
- Routine maintenance
67-
- Self-explanatory refactors
68-
- Simple one-file changes
69-
70-
### Discovery
71-
72-
Before starting work, understand project context:
73-
74-
```bash
75-
# View work distribution
76-
lean-spec stats
48+
1. **Discover context** → Use `board` tool to see project state
49+
2. **Search for related work** → Use `search` tool before creating new specs
50+
3. **Never create files manually** → Always use `create` tool for new specs
7751

78-
# See specs by status
79-
lean-spec board
52+
> **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
8053
81-
# Show statistics and velocity
82-
lean-spec stats
54+
### First Principles (Priority Order)
8355

84-
# Find specs by tag
85-
lean-spec list --tag=api
56+
1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
57+
2. **Signal-to-Noise** - Every word must inform a decision
58+
3. **Intent Over Implementation** - Capture why, let how emerge
59+
4. **Bridge the Gap** - Both human and AI must understand
60+
5. **Progressive Disclosure** - Add complexity only when pain is felt
8661

87-
# Full-text search
88-
lean-spec search "<query>"
62+
### When to Create a Spec
8963

90-
# View a spec
91-
lean-spec view NNN
64+
| ✅ Write spec | ❌ Skip spec |
65+
| ------------------------------------------ | -------------------------- |
66+
| Multi-part features (>2 days work) | Bug fixes |
67+
| Breaking changes | Trivial changes |
68+
| Design decisions | Self-explanatory refactors |
69+
| Architecture affecting multiple components | Simple one-file changes |
70+
71+
### 🔧 Managing Specs
72+
73+
#### MCP Tools (Preferred) with CLI Fallback
74+
75+
| Action | MCP Tool | CLI Fallback |
76+
| -------------- | -------- | ---------------------------------------------- |
77+
| Project status | `board` | `lean-spec board` |
78+
| List specs | `list` | `lean-spec list` |
79+
| Search specs | `search` | `lean-spec search "query"` |
80+
| View spec | `view` | `lean-spec view <spec>` |
81+
| Create spec | `create` | `lean-spec create <name>` |
82+
| Update spec | `update` | `lean-spec update <spec> --status <status>` |
83+
| Link specs | `link` | `lean-spec link <spec> --depends-on <other>` |
84+
| Unlink specs | `unlink` | `lean-spec unlink <spec> --depends-on <other>` |
85+
| Dependencies | `deps` | `lean-spec deps <spec>` |
86+
| Token count | `tokens` | `lean-spec tokens <spec>` |
87+
88+
### ⚠️ Core Rules
89+
90+
| Rule | Details |
91+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
92+
| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on` |
93+
| **ALWAYS link spec references** | Content mentions another spec → `lean-spec link <spec> --depends-on <other>` |
94+
| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
95+
| **No nested code blocks** | Use indentation instead |
96+
97+
### 🚫 Common Mistakes
98+
99+
| ❌ Don't | ✅ Do Instead |
100+
| -------------------------- | ------------------------------------- |
101+
| Create spec files manually | Use `create` tool |
102+
| Skip discovery | Run `board` and `search` first |
103+
| Leave status as "planned" | Update to `in-progress` before coding |
104+
| Edit frontmatter manually | Use `update` tool |
105+
106+
### 📋 SDD Workflow
92107

93-
# Check dependencies
94-
lean-spec deps <spec>
108+
```
109+
BEFORE: board → search → check existing specs
110+
DURING: update status to in-progress → code → document decisions → link dependencies
111+
AFTER: update status to complete → document learnings
95112
```
96113

97-
These commands help you understand what exists, what's in progress, and what depends on what.
98-
99-
**Core fields:**
114+
**Status tracks implementation, NOT spec writing.**
100115

101-
- `status` are required
102-
- `tags` help with discovery and organization
103-
- `priority` helps teams plan work
116+
### Spec Dependencies
104117

105-
### Workflow
118+
Use `depends_on` to express blocking relationships between specs:
106119

107-
1. **Discover context** - Run `lean-spec stats` or `lean-spec board` to see current state
108-
2. **Search existing specs** - Use `lean-spec search` or `lean-spec list` to find relevant work
109-
3. **Check dependencies** - Run `lean-spec deps <spec>` if working on existing spec
110-
4. **Create or update spec** - Add frontmatter with required fields and helpful metadata
111-
5. **Implement changes** - Keep spec in sync as you learn
112-
6. **Update status** - Mark progress: `planned` → `in-progress` → `complete`
113-
7. **Archive when done** - `lean-spec archive <spec>` moves to archive
120+
- **`depends_on`** = True blocker, work order matters, directional (A depends on B)
114121

115-
### Update Commands
122+
Link dependencies when one spec builds on another:
116123

117124
```bash
118-
# Update spec status
119-
lean-spec update <spec> --status in-progress
120-
121-
# Or edit frontmatter directly in the markdown file
125+
lean-spec link <spec> --depends-on <other-spec>
122126
```
123127

128+
### Token Thresholds
129+
130+
| Tokens | Status |
131+
| ----------- | --------------------- |
132+
| <2,000 | ✅ Optimal |
133+
| 2,000-3,500 | ✅ Good |
134+
| 3,500-5,000 | ⚠️ Consider splitting |
135+
| >5,000 | 🔴 Must split |
136+
124137
### Quality Standards
125138

126139
- Code is clear and maintainable
127140
- Tests cover critical paths
128141
- No unnecessary complexity
129142
- Documentation where needed (not everywhere)
130143
- Specs stay in sync with implementation
144+
145+
---
146+
147+
**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!

‎specs/014-core-simplification/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
status: planned
3+
created: '2025-12-05'
4+
tags: [architecture, simplification, go, refactor]
5+
priority: high
6+
created_at: '2025-12-05T03:18:55.302Z'
7+
---
8+
9+
# 014-core-simplification
10+
11+
> **Status**: 📅 Planned · **Priority**: High · **Created**: 2025-12-05
12+
13+
## Overview
14+
15+
Reposition devlog as a **Go-only AI agent event collector and parser**. The current TypeScript/Node.js codebase has accumulated unnecessary complexity. Go provides the right foundation: single binary, low resource footprint, excellent concurrency for file watching and event streaming.
16+
17+
### Core Mission
18+
19+
A lightweight daemon that:
20+
21+
1. **Watches** AI coding tool log files (Copilot, Cursor, Claude, Windsurf, etc.)
22+
2. **Parses** sessions and events into structured data
23+
3. **Sends** events to configurable remote endpoints (agent-relay, custom backends)
24+
25+
### Why Go-Only?
26+
27+
- Single static binary - no Node.js/npm runtime dependencies
28+
- Low memory footprint for always-on daemon
29+
- Excellent file watching and concurrent I/O
30+
- Already have `collector-go/` as foundation
31+
- Matches agent-relay's Go backend
32+
33+
### What Gets Removed
34+
35+
- **All TypeScript packages** (`packages/*` except `collector-go`)
36+
- **All Node.js tooling** (pnpm, turbo, vitest, etc.)
37+
- **Web UI** (`apps/web/`)
38+
- **Prisma/database layer** - events sent to remote, not stored locally
39+
40+
## Design
41+
42+
### Target Architecture
43+
44+
```
45+
devlog (Go-only)
46+
├── cmd/
47+
│ └── devlog/ # Main binary entry point
48+
├── internal/
49+
│ ├── watcher/ # File system watching
50+
│ ├── parser/ # Log parsing (Copilot, Cursor, Claude, etc.)
51+
│ ├── events/ # Event types and serialization
52+
│ └── sender/ # Remote event dispatch
53+
├── pkg/ # Public APIs if needed
54+
└── configs/ # Default configurations
55+
```
56+
57+
### Event Flow
58+
59+
```
60+
[Log Files] → [Watcher] → [Parser] → [Events] → [Sender] → [Remote]
61+
↓
62+
agent-relay / custom
63+
```
64+
65+
### Configuration
66+
67+
```yaml
68+
# ~/.config/devlog/config.yaml
69+
watchers:
70+
- name: copilot
71+
path: ~/.config/github-copilot/logs/
72+
parser: copilot
73+
- name: cursor
74+
path: ~/.cursor/logs/
75+
parser: cursor
76+
77+
remote:
78+
endpoint: http://localhost:8080/api/events
79+
# or: ws://localhost:8080/ws/events
80+
auth_token: ${DEVLOG_TOKEN}
81+
batch_size: 100
82+
flush_interval: 5s
83+
```
84+
85+
### Supported Parsers (Initial)
86+
87+
- GitHub Copilot
88+
- Cursor
89+
- Claude Code (Anthropic)
90+
- Windsurf
91+
- Generic JSON/JSONL
92+
93+
### Remote Integration
94+
95+
Events are POSTed or streamed via WebSocket to configurable endpoints:
96+
97+
- **agent-relay**: Native integration for session visualization
98+
- **Custom backends**: Webhook-style event ingestion
99+
- **stdout**: For piping to other tools
100+
101+
## Plan
102+
103+
- [ ] Phase 1: Audit `collector-go/` - identify reusable parsing logic
104+
- [ ] Phase 2: Design event schema and remote API contract
105+
- [ ] Phase 3: Implement core watcher → parser → sender pipeline
106+
- [ ] Phase 4: Add parser support (Copilot, Cursor, Claude, Windsurf)
107+
- [ ] Phase 5: Configuration and CLI interface
108+
- [ ] Phase 6: Remove all TypeScript/Node.js code
109+
- [ ] Phase 7: Update build/release (single binary, Docker image)
110+
- [ ] Phase 8: Document agent-relay integration
111+
112+
## Test
113+
114+
- [ ] Daemon starts and watches configured paths
115+
- [ ] Events parsed correctly for each supported tool
116+
- [ ] Events sent to remote endpoint with retries
117+
- [ ] Single binary works without external dependencies
118+
- [ ] Configuration loading from file and env vars
119+
120+
## Notes
121+
122+
### Migration from TypeScript
123+
124+
| Current | Action |
125+
| ------------------------ | -------------------------- |
126+
| `packages/collector-go/` | Promote to root, expand |
127+
| `packages/collector/` | Port parsing logic to Go |
128+
| `packages/core/` | Port event types to Go |
129+
| `packages/ai/` | Remove (not needed) |
130+
| `packages/cli/` | Replace with Go CLI |
131+
| `packages/mcp/` | Remove or separate project |
132+
| `packages/shared/` | Remove |
133+
| `packages/web/` | Remove |
134+
| `apps/web/` | Remove |
135+
| `prisma/` | Remove (no local DB) |
136+
137+
### Event Schema (Draft)
138+
139+
```go
140+
type Event struct {
141+
ID string `json:"id"`
142+
Type string `json:"type"` // session_start, completion, error, etc.
143+
Source string `json:"source"` // copilot, cursor, claude, etc.
144+
Timestamp time.Time `json:"timestamp"`
145+
SessionID string `json:"session_id,omitempty"`
146+
Data map[string]any `json:"data"`
147+
}
148+
```
149+
150+
### Open Questions
151+
152+
1. Should we embed agent-relay integration or keep it generic?
153+
2. Local event buffering strategy when remote is unavailable?
154+
3. Plugin system for custom parsers?

0 commit comments

Comments
 (0)