Files

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

  1. CLI Tool (cli/followups-cli.js)

    • Standalone, framework-agnostic
    • Handles API communication
    • Formats output for different channels
    • Can be used outside Bot
  2. Handler (handler.js)

    • Bridges Bot and CLI tool
    • Detects channel capabilities
    • Manages command registration
    • Handles auto-trigger mode
  3. Context Extraction

    • Last 1-3 conversation exchanges
    • Format: [{user: "...", assistant: "..."}]
    • Optimized for relevance vs cost
  4. 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.sh with 5 modes
  • Sample data: test-example.json (Docker Q&A)
  • Unit tests: Planned for v1.1.0


๐Ÿท๏ธ 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)

  1. README.md - Understand features
  2. QUICKSTART.md - Set it up
  3. Test with ./test.sh
  4. Integrate with Bot via SKILL.md

Intermediate (Customizing)

  1. examples.md - See output variations
  2. SKILL.md - Advanced configuration
  3. Modify prompts in cli/followups-cli.js
  4. Add custom categories

Advanced (Contributing)

  1. INTERNAL.md - Architecture deep dive
  2. CONTRIBUTING.md - Contribution guidelines
  3. Study prompt engineering section
  4. 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 with npm install)
  • package-lock.json (auto-generated)
  • API keys (never commit!)

Distribution Channels

  1. Skills: Primary distribution
  2. npm: Standalone CLI tool
  3. 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)