Skip to content

Commit 412afc7

Browse files
grokifyclaude
grokify
and
claude
committed
docs: add CLAUDE.md and project specs
Add project-level agent guidelines and specification documents: - CLAUDE.md: repo conventions for Claude Code - ARCHITECTURE.md: system design and integrations - PRD.md: product requirements - TRD.md: technical requirements - PLAN.md: implementation phases - ROADMAP.md: current roadmap with RMI tracking Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 688211c commit 412afc7

7 files changed

Lines changed: 2468 additions & 1877 deletions

File tree

‎CLAUDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# CLAUDE.md — aha-studio
2+
3+
CLI tools for [Aha!](https://www.aha.io/) product management: AQL (Aha Query Language) with a lexer→parser→planner→executor pipeline, an MCP server built on `plexusone/omniskill`, local SQLite sync with FTS5, optional Neo4j graph analytics, and an HTTP API server. Specs live in `docs/specs/` (ARCHITECTURE, PRD, TRD, PLAN, ROADMAP); completed historical phases are in `docs/specs/ROADMAP_HISTORY.md`.
4+
5+
## PRISM Control
6+
7+
This repo's roadmap items are tracked in [prism-control](https://github.com/ProductBuildersHQ/prism-control). Use `prismctl work ready --repo github.com/grokify/aha-studio` to find claimable work, and carry the `Refs: RMI-AHASTUDIO-<NNN>` trailer on every commit.

‎docs/specs/ARCHITECTURE.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Aha Studio Architecture
2+
3+
## Overview
4+
5+
Aha Studio is a Go application providing AQL (Aha Query Language), MCP server integration, local SQLite sync, Neo4j graph analytics, and an HTTP API for Aha.io product management data.
6+
7+
## System Architecture
8+
9+
```text
10+
┌──────────────────────────────┐
11+
│ Entry Points │
12+
│ │
13+
│ CLI (cobra) MCP (stdio) │
14+
│ REPL HTTP API │
15+
└──────────┬───────────────────┘
16+
│
17+
┌──────────▼───────────────────┐
18+
│ Studio (Facade) │
19+
│ studio/studio.go │
20+
└──────────┬───────────────────┘
21+
│
22+
┌────────────────────┼────────────────────┐
23+
│ │ │
24+
┌────────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐
25+
│ AQL Pipeline │ │ MCP Server │ │ HTTP Server │
26+
│ │ │ mcp/ │ │ httpserver/ │
27+
│ lexer → parser │ │ │ │ │
28+
│ → ast │ │ OmniSkill skill │ │ REST endpoints │
29+
│ → validator │ │ 40+ tools │ │ CORS/Auth │
30+
│ → planner │ │ Resources │ │ Query modes │
31+
│ → executor │ │ │ │ │
32+
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
33+
│ │ │
34+
└────────────┬──────┴─────────────────────┘
35+
│
36+
┌────────────▼────────────────────────────┐
37+
│ Data Layer │
38+
│ │
39+
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
40+
│ │ Aha API │ │ SQLite │ │ Neo4j │ │
41+
│ │ (live) │ │ (cache) │ │ (graph) │ │
42+
│ │ aha-go │ │ sync/ │ │ graph/ │ │
43+
│ └──────────┘ └──────────┘ └──────────┘ │
44+
└─────────────────────────────────────────┘
45+
```
46+
47+
## AQL Pipeline
48+
49+
The query engine follows a classic compiler pipeline:
50+
51+
```text
52+
AQL string
53+
│
54+
▼
55+
Lexer (aql/lexer/)
56+
│ Tokenization
57+
▼
58+
Parser (aql/parser/)
59+
│ Recursive descent, operator precedence
60+
▼
61+
AST (aql/ast/)
62+
│ SELECT, FROM, WHERE, JOIN, GROUP BY, HAVING,
63+
│ ORDER BY, LIMIT, INSERT, UPDATE, DELETE
64+
▼
65+
Validator (aql/validator/)
66+
│ Semantic validation against entity schema
67+
▼
68+
Planner (planner/)
69+
│ Filter pushdown, custom field detection,
70+
│ JOIN strategy, aggregation planning
71+
▼
72+
Executor (executor/)
73+
│ API calls, client-side filtering, aggregation,
74+
│ JOIN resolution, mutation execution
75+
▼
76+
Result (result/)
77+
│ Records, metadata, formatting
78+
▼
79+
Output (table / JSON / CSV / YAML / Markdown / HTML / XLSX)
80+
```
81+
82+
## MCP Server
83+
84+
Built on the OmniSkill framework (`github.com/plexusone/omniskill`), which provides:
85+
86+
- Skill/Tool abstraction over the MCP protocol
87+
- Transport options: stdio (Claude Desktop), HTTP/SSE
88+
- Direct library-mode invocation without JSON-RPC overhead
89+
90+
The MCP server exposes 40+ tools across entity types (features, ideas, releases, epics, goals, initiatives, requirements, products, strategic models, comments) with full CRUD operations plus lookup/reference helpers.
91+
92+
### Key files
93+
94+
| File | Responsibility |
95+
|------|----------------|
96+
| `mcp/skill.go` | AhaSkill definition, tool registration |
97+
| `mcp/handlers.go` | Tool handler implementations |
98+
| `mcp/config.go` | MCP server configuration |
99+
100+
## Data Layer
101+
102+
### Aha API (aha-go)
103+
104+
Primary data source. All live queries go through `github.com/grokify/aha-go`, which wraps the Aha.io REST API.
105+
106+
### SQLite (sync/)
107+
108+
Local cache for offline and hybrid query modes.
109+
110+
- Full entity sync with incremental updates via `updated_since`
111+
- Schema migrations for evolving entity models
112+
- FTS5 full-text search across entities
113+
- Saved filters persistence
114+
- Three query modes: `api` (live only), `offline` (cache only), `prefer-cache` (cache first, API fallback)
115+
116+
### Neo4j (graph/)
117+
118+
Graph analytics for entity relationships.
119+
120+
- Feature dependency graphs
121+
- Release dependency analysis
122+
- Initiative impact mapping
123+
- Product overview aggregation
124+
- Raw Cypher query support
125+
126+
### In-Memory Cache (cache/)
127+
128+
LRU cache with TTL for API response caching. Thread-safe, configurable size and expiration.
129+
130+
## HTTP API
131+
132+
REST server (`httpserver/`) exposing AQL queries, sync management, saved filters, full-text search, and Neo4j graph endpoints. See ROADMAP.md Phase 11 for the full endpoint list.
133+
134+
## Ecosystem Position
135+
136+
```text
137+
Grokify Org
138+
─────────────────────────────────
139+
aha-go Aha.io API client
140+
aha-studio AQL + MCP + sync + graph
141+
142+
│
143+
│ OmniSignal adapter
144+
│ (Aha Ideas → enhancement signals)
145+
▼
146+
147+
PlexusOne Org
148+
─────────────────────────────────
149+
omniskill MCP skill framework
150+
omnisignal Signal normalization
151+
152+
│
153+
│ references
154+
▼
155+
156+
ProductBuildersHQ Org
157+
─────────────────────────────────
158+
market-spec Market intelligence entities
159+
organization-spec Customer/prospect entities
160+
prism-roadmap Strategic planning
161+
```
162+
163+
Aha Studio bridges Aha.io into the broader ProductContext ecosystem. The OmniSignal adapter converts Aha-specific concepts (Ideas, Idea Portals, custom fields) into vendor-neutral signals that OmniSignal can aggregate with evidence from other sources.
164+
165+
## Dependencies
166+
167+
| Module | Purpose |
168+
|--------|---------|
169+
| `github.com/grokify/aha-go` | Aha.io REST API client |
170+
| `github.com/plexusone/omniskill` | MCP skill infrastructure |
171+
| `github.com/modelcontextprotocol/go-sdk` | Official MCP Go SDK |
172+
| `github.com/spf13/cobra` | CLI framework |
173+
| `github.com/c-bata/go-prompt` | Interactive REPL |
174+
| `github.com/xuri/excelize/v2` | Excel export |
175+
| `modernc.org/sqlite` | Pure Go SQLite driver |
176+
| `github.com/neo4j/neo4j-go-driver` | Neo4j graph database |

‎docs/specs/PLAN.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Aha Studio Implementation Plan
2+
3+
## Scope
4+
5+
This plan covers remaining and upcoming work only. Completed phases (1 through 10a, and most of 10b) are recorded in [ROADMAP.md](ROADMAP.md), which remains the authoritative per-phase status tracker. Update ROADMAP.md status tables as items below land.
6+
7+
## Workstream 1: Phase 12 — Feature-Release Query Support (In Progress)
8+
9+
Enable querying features by release date or name from the local cache. Sync-side capture of `release_id` is complete; the query layer remains.
10+
11+
| Item | Package | Notes |
12+
|------|---------|-------|
13+
| Feature→Release relationship rows | `sync/` | Insert `BELONGS_TO` rows into the relationships table during sync |
14+
| `GetFeaturesByReleaseDate` | `sync/db.go` | Date-indexed lookup joining features to releases |
15+
| `GetFeaturesByReleaseName` | `sync/db.go` | Name-based lookup |
16+
| AQL `release.date` support | `planner/`, `executor/` | Qualifier syntax already exists for `custom.*`; extend to `release.*` |
17+
| AQL `release.name` support | `planner/`, `executor/` | Same mechanism |
18+
| `list_features_by_release_date` MCP tool | `mcp/` | Thin wrapper over the db methods |
19+
20+
Depends on `aha-go` returning release details with features (in place as of v0.7.0 usage).
21+
22+
## Workstream 2: Phase 11 — HTTP API Remainder (In Progress)
23+
24+
Core server, saved filters, search, and graph endpoints are complete.
25+
26+
| Item | Priority | Notes |
27+
|------|----------|-------|
28+
| OpenAPI 3.0 specification | Medium | Generate or hand-author; serve at `/api/openapi.json`; enables client generation |
29+
| `/metrics` Prometheus endpoint | Low | Query counts, latencies, cache hit rate |
30+
| WebSocket streaming | Low | Stream large result sets; defer until a concrete consumer exists |
31+
32+
## Workstream 3: Phase 10b Gaps — Remaining Write Tools
33+
34+
Small, independent items; good batch for a single release.
35+
36+
| Tool | Notes |
37+
|------|-------|
38+
| `create_idea` | `aha-go` `CreateIdea()` exists per ROADMAP dependency table |
39+
| `create_release` | Pair with existing `update_release` |
40+
| `add_goal_to_feature` / `remove_goal_from_feature` | Goal-feature linking |
41+
| `get_feature_ideas` | Ideas promoted to a feature |
42+
| `list_idea_categories` | Category lookup with caching |
43+
| `delete_idea` | Low priority; destructive, require confirmation semantics |
44+
45+
## Workstream 4: Phase 10c — Analytics and Statistics Tools
46+
47+
Aggregated metrics without fetching all records to the client.
48+
49+
| Item | Notes |
50+
|------|-------|
51+
| `get_ideas_statistics` | Counts by status/category, vote stats, top ideas per group |
52+
| `get_features_statistics` | Counts by release/status, requirements summary |
53+
| `get_idea_voter_domains` | Unique voter domain analytics |
54+
55+
Prefer computing from the SQLite cache when synced (fast, no API quota); fall back to API aggregation.
56+
57+
## Workstream 5: OmniSignal Adapter (New)
58+
59+
Bridges Aha Studio into the ProductContext ecosystem. See TRD.md for the IR contract.
60+
61+
| Step | Deliverable |
62+
|------|-------------|
63+
| 1 | Adapter package (e.g., `omnisignal/` in this repo) mapping Aha Idea → enhancement signal IR |
64+
| 2 | Product/category normalization: map Aha products and idea categories to canonical IDs |
65+
| 3 | Metrics extraction: votes, subscribers, organizations, named customers, opportunities, estimated ARR |
66+
| 4 | Lifecycle mapping: Aha workflow status → normalized status, plus `ageDays` from created date |
67+
| 5 | Batch export command (`aha-studio signals export`) and/or provider registration with `plexusone/omnisignal` |
68+
| 6 | Round-trip tests against recorded fixtures; no live API in unit tests |
69+
70+
Coordinate the IR schema with `plexusone/omnisignal` (runtime) and `plexusone/signal-spec` (canonical model) before implementing step 1 — the signal schema is owned there, not here.
71+
72+
## Workstream 6: Phase 13 — DuckDB Migration (Planned, Last)
73+
74+
Columnar engine for analytical queries. Deliberately sequenced after Phases 10c and 12 so real query patterns inform the design.
75+
76+
| Step | Notes |
77+
|------|-------|
78+
| 1 | Benchmark current SQLite performance on representative analytics queries |
79+
| 2 | Feature-flagged DuckDB backend for entity data; SQLite retained for sync metadata |
80+
| 3 | Parquet export support |
81+
| 4 | Validate and flip default, or drop if SQLite proves sufficient |
82+
83+
## Workstream 7: Phase 10d — External Integrations (Planned)
84+
85+
Jira fetch/search, Confluence read/search, and AI workflow tools (`review_idea`, `triage_new_ideas`, `groom_feature`). Lowest priority; revisit scope after the OmniSignal adapter ships, since some cross-system use cases may be better served at the OmniSignal layer than inside Aha Studio.
86+
87+
## Sequencing Summary
88+
89+
1. Phase 12 completion (small, unblocks release-based reporting)
90+
2. Phase 10b gap tools (small batch release)
91+
3. OmniSignal adapter (strategic; needs schema coordination first)
92+
4. Phase 11 remainder (OpenAPI spec first)
93+
5. Phase 10c analytics tools
94+
6. Phase 13 DuckDB evaluation
95+
7. Phase 10d integrations
96+
97+
## Release Discipline
98+
99+
Each workstream should ship as its own tagged release following the pre-push checklist: no local `replace` directives (one currently exists in `go.mod` for `aha-go` and must be resolved before pushing), tests and lint green, CI passing before tagging, conventional commits throughout.

‎docs/specs/PRD.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Aha Studio Product Requirements
2+
3+
## Product Summary
4+
5+
Aha Studio provides a query language (AQL), MCP server, and analytics platform for Aha.io product management data. It enables product managers, engineers, and AI agents to query, analyze, and manage Aha.io data through SQL-like syntax, programmatic APIs, and natural language via MCP.
6+
7+
## Personas
8+
9+
| Persona | Description | Primary Use |
10+
|---------|-------------|-------------|
11+
| Product Manager | Uses Aha.io daily for roadmap and idea management | AQL for ad-hoc queries, reports, and bulk operations |
12+
| Engineering Lead | Builds integrations and automation around product data | Library mode, HTTP API, MCP server for AI workflows |
13+
| AI Agent | Claude or other LLM assistants via MCP | Natural language product management through 40+ MCP tools |
14+
| Data Analyst | Analyzes product signals and trends | SQLite offline queries, Excel export, graph analytics |
15+
16+
## Use Cases
17+
18+
### Query and Reporting
19+
20+
- Execute SQL-like queries against Aha.io data (features, ideas, releases, epics, goals, initiatives, requirements)
21+
- Aggregate and group data (COUNT, SUM, AVG, MIN, MAX with GROUP BY/HAVING)
22+
- Join related entities (features with releases, ideas with features)
23+
- Export results in multiple formats (table, JSON, CSV, YAML, Markdown, HTML, Excel)
24+
25+
### AI-Assisted Product Management
26+
27+
- AI agents query and manage Aha.io data via MCP tools
28+
- Natural language to AQL translation
29+
- Full CRUD operations on features, ideas, releases, epics, goals, initiatives, requirements, and comments
30+
- Workflow status management and user assignment
31+
- Strategic model management
32+
33+
### Offline Analysis
34+
35+
- Sync Aha.io data to local SQLite database
36+
- Full-text search across all entities
37+
- Incremental sync with change tracking
38+
- Hybrid query modes (live API, offline cache, or prefer-cache)
39+
40+
### Graph Analytics
41+
42+
- Feature dependency analysis via Neo4j
43+
- Release dependency mapping
44+
- Initiative impact assessment
45+
- Cross-entity relationship exploration
46+
47+
### OmniSignal Integration
48+
49+
- Map Aha Ideas to OmniSignal enhancement signals
50+
- Normalize Aha-specific fields (votes, categories, custom fields) into vendor-neutral signal metrics
51+
- Enable frustration scoring (votes x age) across Aha and non-Aha sources
52+
53+
## Functional Requirements
54+
55+
### AQL Engine
56+
57+
- Full SELECT/FROM/WHERE/ORDER BY/LIMIT/GROUP BY/HAVING/JOIN syntax
58+
- INSERT/UPDATE/DELETE mutations with dry-run and confirmation
59+
- Subqueries (scalar and list)
60+
- DISTINCT, aliases, and aggregate functions
61+
- Custom field queries via `custom.fieldname` syntax
62+
- Tags as a derived entity with usage counts
63+
64+
### MCP Server
65+
66+
- 40+ tools covering all major Aha.io entity types
67+
- Lookup/reference tools for resolving names to IDs
68+
- Comment management across features, ideas, and epics
69+
- Custom field definitions and options listing
70+
- OmniSkill-based skill registration with stdio and HTTP transport
71+
72+
### Interactive Experience
73+
74+
- REPL with tab completion, syntax highlighting, and query history
75+
- Saved queries in configuration file
76+
- Configuration profiles for multiple Aha.io accounts
77+
78+
### HTTP API
79+
80+
- REST endpoints for AQL queries, sync, filters, search, and graph analytics
81+
- CORS and API key authentication middleware
82+
- Query mode selection per request
83+
- Background sync scheduling
84+
85+
### Data Management
86+
87+
- SQLite sync with schema migrations
88+
- FTS5 full-text search
89+
- In-memory LRU cache with TTL
90+
- Neo4j graph sync and Cypher query support
91+
92+
## Non-Functional Requirements
93+
94+
- Pure Go SQLite driver (no CGo dependency)
95+
- Concurrent API pagination and JOIN fetches
96+
- Thread-safe cache operations
97+
- CLI commands follow Cobra conventions
98+
- Go module at `github.com/grokify/aha-studio`

0 commit comments

Comments
 (0)