7.4 KiB
Smart Follow-up Suggestions - Project Index
Complete file reference and navigation guide
Version: 1.0.0
Created: January 20, 2026
Status: โ
Production Ready
๐ Project Structure
smart-followups/
โโโ cli/
โ โโโ followups-cli.js # Main CLI tool (9.5KB)
โโโ node_modules/ # Dependencies (not in git)
โโโ .gitignore # Git ignore rules
โโโ CHANGELOG.md # Version history
โโโ CONTRIBUTING.md # Contribution guidelines
โโโ examples.md # Channel output examples
โโโ handler.js # Bot integration handler (5.6KB)
โโโ INTERNAL.md # Architecture & design docs (22KB)
โโโ LICENSE # MIT License
โโโ package.json # Package metadata
โโโ package-lock.json # Dependency lock file (not in git)
โโโ PROJECT_INDEX.md # This file
โโโ QUICKSTART.md # 5-minute setup guide
โโโ README.md # Main documentation
โโโ SKILL.md # Bot integration guide (9.4KB)
โโโ test-example.json # Sample conversation data
โโโ test.sh # Test script
๐ File Guide
๐ Start Here
| File | Purpose | Audience |
|---|---|---|
| README.md | Feature overview, quick start | Everyone |
| QUICKSTART.md | 5-minute setup instructions | New users |
| SKILL.md | Bot integration guide | Bot users |
๐ ๏ธ Core Code
| File | Purpose | Lines | Key Functions |
|---|---|---|---|
| cli/followups-cli.js | Standalone CLI tool | ~300 | generateFollowups(), formatOutput(), buildPrompt() |
| handler.js | Bot integration | ~150 | handleFollowupsCommand(), autoGenerateFollowups() |
๐ Documentation
| File | Purpose | Length | When to Read |
|---|---|---|---|
| README.md | Overview & features | 5KB | First visit |
| QUICKSTART.md | Fast setup guide | 3.6KB | Getting started |
| SKILL.md | Integration details | 9.4KB | Integrating with Bot |
| examples.md | Output samples | 11.6KB | Seeing how it works |
| INTERNAL.md | Architecture & design | 22KB | Understanding internals |
| CONTRIBUTING.md | How to contribute | 7.2KB | Want to contribute |
| CHANGELOG.md | Version history | 2.3KB | Checking updates |
โ๏ธ Configuration
| File | Purpose |
|---|---|
| package.json | Project metadata, dependencies, scripts |
| .gitignore | Files excluded from git |
| LICENSE | MIT License terms |
๐งช Testing
| File | Purpose |
|---|---|
| test.sh | Automated test script |
| test-example.json | Sample conversation data for testing |
๐ฏ Quick Navigation
I want to...
...understand what this does
โ Read README.md
...set it up quickly
โ Follow QUICKSTART.md
...integrate with Bot
โ Read SKILL.md
...see example outputs
โ Check examples.md
...understand the architecture
โ Study INTERNAL.md
...contribute code
โ Review CONTRIBUTING.md
...use it standalone (no Bot)
โ Use cli/followups-cli.js directly
...modify the prompt
โ Edit buildPrompt() in cli/followups-cli.js
...add a new channel
โ Update supportsInlineButtons() in handler.js
...troubleshoot issues
โ See QUICKSTART.md โ Troubleshooting section
๐ Key Concepts
Core Components
-
CLI Tool (
cli/followups-cli.js)- Standalone, framework-agnostic
- Handles API communication
- Formats output for different channels
- Can be used outside Bot
-
Handler (
handler.js)- Bridges Bot and CLI tool
- Detects channel capabilities
- Manages command registration
- Handles auto-trigger mode
-
Context Extraction
- Last 1-3 conversation exchanges
- Format:
[{user: "...", assistant: "..."}] - Optimized for relevance vs cost
-
Suggestion Categories
- โก Quick: Clarifications, next steps
- ๐ง Deep Dive: Technical depth
- ๐ Related: Connected topics
Output Modes
| Mode | Format | Use Case |
|---|---|---|
json |
Raw JSON object | API integration, debugging |
telegram |
Button array | Telegram inline keyboards |
text |
Numbered list with headers | Signal, iMessage |
compact |
Simple numbered list | SMS, email |
Channel Support
Interactive (Inline Buttons):
- Telegram โ
- Discord โ
- Slack โ
Text (Numbered Lists):
- Signal โ
- iMessage โ
- SMS โ
- Email โ
๐ File Statistics
Code
- Total lines: ~450 (CLI + Handler)
- Languages: JavaScript (100%)
- Dependencies: 1 direct (
@anthropic-ai/sdk)
Documentation
- Total words: ~15,000
- Total docs: 7 markdown files
- Code comments: ~80 lines
Test Coverage
- Manual tests:
test.shwith 5 modes - Sample data:
test-example.json(Docker Q&A) - Unit tests: Planned for v1.1.0
๐ External Links
- Anthropic API: https://docs.anthropic.com
- Bot: (Add link when available)
- Skills: https://skills.com (when published)
- Chameleon AI Chat: https://github.com/robbyczgw-cla/Chameleon-AI-Chat (private)
- Issues: https://github.com/robbyczgw-cla/bot-smart-followups/issues
๐ท๏ธ Tags & Keywords
Primary: bot, skill, ai, follow-up, suggestions
Secondary: telegram, discord, conversation, claude, haiku
Technical: node.js, anthropic, inline-buttons, messaging
๐ Version Timeline
- v1.0.0 (Jan 20, 2026) - Initial release
- v1.1.0 (Planned) - Caching, rate limiting, tests
- v2.0.0 (Future) - Personalization, multi-language
โ Pre-Publishing Checklist
Before publishing to Skills:
- All core files present
- Documentation complete
- CLI tool functional
- Handler integration ready
- Examples provided
- License included (MIT)
- Package.json configured
- npm package published
- GitHub repository public
- Skills submission
- User testing (Telegram)
๐ Learning Path
Beginner (Just using it)
- README.md - Understand features
- QUICKSTART.md - Set it up
- Test with
./test.sh - Integrate with Bot via SKILL.md
Intermediate (Customizing)
- examples.md - See output variations
- SKILL.md - Advanced configuration
- Modify prompts in
cli/followups-cli.js - Add custom categories
Advanced (Contributing)
- INTERNAL.md - Architecture deep dive
- CONTRIBUTING.md - Contribution guidelines
- Study prompt engineering section
- Extend for new channels
๐พ Backup & Distribution
What to Include in Backups
- All source files (cli/, handler.js)
- Documentation (all .md files)
- Configuration (package.json)
- Test data (test-example.json, test.sh)
What to Exclude
node_modules/(regenerate withnpm install)package-lock.json(auto-generated)- API keys (never commit!)
Distribution Channels
- Skills: Primary distribution
- npm: Standalone CLI tool
- GitHub: Source code, issues, PRs
Maintained by: @robbyczgw-cla
Last Updated: January 20, 2026
File Count: 14 (excluding node_modules)
Total Size: ~70KB (excluding dependencies)