diff --git a/README.md b/README.md index f5988048..1bf342c3 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ A command-line interface for dynamically assembling context for AI coding agents This tool collects context from predefined rule files and a task-specific prompt, substitutes parameters, and prints a single, combined context to standard output. This is useful for feeding a large amount of relevant information into an AI model like Claude, Gemini, or OpenAI's GPT series. -**๐Ÿ“– [View Full Documentation](https://kitproj.github.io/coding-context-cli/)** +**๐Ÿ“– [View Full Documentation](https://kitproj.github.io/coding-context-cli/)** +**๐Ÿ“Š [View Slide Deck](./SLIDES.md)** | [Download PDF](./SLIDES.pdf) | [How to Present](./SLIDES_README.md) ## Features @@ -664,3 +665,23 @@ selectors: # Implementation Task ... ``` + +## Presentations + +A comprehensive slide deck is available for presenting and learning about the Coding Context CLI: + +- **[View Slide Deck](./SLIDES.md)** - Full presentation with 50+ slides +- **[Presentation Guide](./SLIDES_README.md)** - How to view, export, and present +- **[Example Usage](./examples/PRESENTATION.md)** - Presentation scenarios and tips + +The slides are written in [Marp](https://marp.app/) format and can be: +- Viewed in VS Code with the Marp extension +- Exported to HTML, PDF, or PowerPoint +- Presented directly from a browser +- Customized for your audience + +Perfect for: +- **Team onboarding** - Introduce the tool to new team members +- **Tech talks** - Present at meetups or conferences +- **Workshops** - Run hands-on training sessions +- **Documentation** - Visual reference for features diff --git a/SLIDES.md b/SLIDES.md new file mode 100644 index 00000000..a364f75d --- /dev/null +++ b/SLIDES.md @@ -0,0 +1,911 @@ +--- +marp: true +theme: default +paginate: true +backgroundColor: #fff +style: | + section { + font-size: 28px; + } + h1 { + color: #2c3e50; + } + h2 { + color: #3498db; + } + code { + background: #f4f4f4; + } + pre { + border-radius: 5px; + } +--- + + +# Coding Context CLI + +**Dynamically Assemble Context for AI Coding Agents** + +A command-line tool that collects, filters, and delivers rich context to AI models + +--- + +## The Problem + +AI coding agents need comprehensive context to make informed decisions: + +- ๐Ÿ“‹ **Project-specific** coding standards and conventions +- ๐Ÿ—๏ธ **Architecture** patterns and structure +- ๐Ÿ”ง **Technology stack** and dependencies +- ๐Ÿ‘ฅ **Team practices** and guidelines +- ๐ŸŽฏ **Task-specific** requirements and constraints + +**Manual assembly is tedious and error-prone** + +--- + +## The Solution: Coding Context CLI + +A tool that **automatically assembles** the right context for AI agents: + +โœ… Discover rules from multiple sources +โœ… Filter based on task requirements +โœ… Substitute runtime parameters +โœ… Support remote rule repositories +โœ… Integrate with any AI agent + +**One command โ†’ Rich, relevant context** + +--- + +## Key Features + +๐Ÿ”„ **Dynamic Context Assembly** +- Merges context from various source files +- Supports multiple file formats and locations + +๐Ÿ“ **Rule-Based Context** +- Reusable context snippets (rules) +- Frontmatter filtering for precision + +๐ŸŽฏ **Task-Specific Prompts** +- Different prompts for different tasks +- Parameter substitution for runtime values + +--- + +## Key Features (continued) + +๐ŸŒ **Remote Directories** +- Load rules from Git, HTTP, S3 +- Share context across teams and projects + +๐Ÿ”ง **Bootstrap Scripts** +- Fetch or generate context dynamically +- Execute setup tasks before context assembly + +๐Ÿ“Š **Token Estimation** +- Monitor context size +- Optimize for model limits + +--- + +## Supported AI Agents + +Works with configuration files from major AI coding tools: + +| Agent | Configuration Files | +|-------|---------------------| +| **Anthropic Claude** | `CLAUDE.md`, `.claude/` | +| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/agents/` | +| **Cursor** | `.cursor/rules`, `.cursorrules` | +| **Google Gemini** | `GEMINI.md`, `.gemini/` | +| **OpenCode.ai** | `.opencode/agent`, `.opencode/rules` | +| **Generic** | `.agents/rules`, `AGENTS.md` | + +--- + +## How It Works + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Rule Files โ”‚ โ† Project standards, architecture, conventions +โ”‚ (.agents/rules)โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ”œโ”€โ”€โ”€โ”€โ”€โ–บ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ โ”‚ Filter by โ”‚ + โ”‚ โ”‚ Selectors โ”‚ + โ”‚ โ”‚ (language, stage)โ”‚ + โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ Task File โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ (.agents/tasks)โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ–ผ + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” + โ”‚ Assembled โ”‚โ”€โ”€โ”€โ”€โ”€โ–บโ”‚ AI Agent โ”‚ + โ”‚ Context โ”‚ โ”‚ (Claude, โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ GPT, etc.) โ”‚ + โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## Installation + +**Linux (AMD64):** +```bash +sudo curl -fsL -o /usr/local/bin/coding-context \ + https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_linux_amd64 +sudo chmod +x /usr/local/bin/coding-context +``` + +**macOS (Apple Silicon):** +```bash +sudo curl -fsL -o /usr/local/bin/coding-context \ + https://github.com/kitproj/coding-context-cli/releases/download/v0.0.23/coding-context_v0.0.23_darwin_arm64 +sudo chmod +x /usr/local/bin/coding-context +``` + +--- + +## Basic Usage + +```bash +coding-context [options] +``` + +**Simple example:** +```bash +coding-context fix-bug | llm -m claude-3-5-sonnet-20241022 +``` + +**With parameters:** +```bash +coding-context -p issue_key=BUG-123 fix-bug | llm -m gemini-pro +``` + +**With selectors:** +```bash +coding-context -s languages=go -s stage=implementation implement-feature +``` + +--- + +## Command-Line Options + +| Option | Description | +|--------|-------------| +| `-C ` | Change to directory before doing anything | +| `-p key=value` | Parameter to substitute in the prompt | +| `-s key=value` | Include rules with matching frontmatter | +| `-a ` | Target agent (excludes that agent's own rules) | +| `-d ` | Remote directory with rules (git::, http://, s3::) | +| `-m ` | URL to manifest file with search paths | +| `-r` | Resume mode: skip rules, select resume task | + +--- + +## Example: Fix a Bug + +**Command:** +```bash +coding-context \ + -s languages=go \ + -s priority=high \ + -p issue_number=PROJ-1234 \ + fix-bug | llm -m claude-3-5-sonnet-20241022 +``` + +**What happens:** +1. Finds task file: `.agents/tasks/fix-bug.md` +2. Includes Go-specific rules with high priority +3. Substitutes `${issue_number}` โ†’ `PROJ-1234` +4. Outputs combined context to AI agent + +--- + +## Rule Files + +Rules are reusable context snippets with optional YAML frontmatter: + +```markdown +--- +languages: + - go +stage: implementation +--- + +# Backend Coding Standards + +- All new code must be accompanied by unit tests +- Use the standard logging library +- Follow Go project layout conventions +``` + +**Selectors match top-level YAML fields only** + +--- + +## Task Files + +Tasks define what the AI agent should do: + +```markdown +--- +selectors: + languages: go + stage: implementation +--- + +# Task: Fix Bug in ${issue_number} + +Analyze the following issue and provide a fix: + +Issue Number: ${issue_number} +Priority: ${priority} +Description: ${description} +``` + +Parameters are substituted at runtime using `-p` flags + +--- + +## Content Expansion + +Task and rule content supports three types of dynamic expansion: + +1. **Parameter Expansion** - `${parameter_name}` + ```markdown + Issue: ${issue_key} + Description: ${description} + ``` + +2. **Command Expansion** - `` !`command` `` + ```markdown + Current date: !`date +%Y-%m-%d` + Git branch: !`git rev-parse --abbrev-ref HEAD` + ``` + +3. **Path Expansion** - `@path` + ```markdown + Current configuration: + @config.yaml + ``` + +--- + +## Remote Directories + +Load rules from remote sources for team collaboration: + +```bash +# From a Git repository +coding-context \ + -d git::https://github.com/company/shared-rules.git \ + fix-bug + +# From HTTP/HTTPS +coding-context \ + -d https://cdn.company.com/coding-standards \ + implement-feature + +# From S3 +coding-context \ + -d s3::https://s3.amazonaws.com/my-bucket/rules \ + deploy +``` + +**Supports:** git, http/https, s3, file, and more via go-getter + +--- + +## Bootstrap Scripts + +Execute scripts before processing rules or tasks: + +**Rule bootstrap** (`.agents/rules/jira-bootstrap`): +```bash +#!/bin/bash +# Install jira-cli if not present +if ! command -v jira-cli &> /dev/null; then + echo "Installing jira-cli..." >&2 + # Installation commands +fi +``` + +**Task bootstrap** (`.agents/tasks/fix-bug-bootstrap`): +```bash +#!/bin/bash +# Fetch issue details +echo "Fetching issue information..." >&2 +jira-cli get-issue ${issue_number} +``` + +--- + +## File Search Paths + +The tool automatically discovers files in multiple locations: + +**Tasks:** +- `./.agents/tasks/*.md` +- `~/.agents/tasks/*.md` + +**Rules:** +- `./.agents/rules/`, `./.cursor/rules/`, `./.github/agents/` +- `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md` +- `~/.agents/rules/`, `~/.claude/`, `~/.gemini/` +- User home and system-wide directories + +**Precedence:** Local โ†’ User home โ†’ System-wide + +--- + +## Frontmatter Selectors + +Filter rules precisely using YAML frontmatter: + +**Rule file:** +```markdown +--- +languages: go +stage: implementation +priority: high +--- +# Go Implementation Guidelines +... +``` + +**Select it:** +```bash +coding-context \ + -s languages=go \ + -s stage=implementation \ + fix-bug +``` + +**Note:** Only top-level YAML fields are supported + +--- + +## Task Frontmatter Selectors + +Tasks can automatically apply selectors: + +```markdown +--- +selectors: + languages: go + stage: implementation +--- +# Implement Feature + +Implement following Go best practices... +``` + +When you run: +```bash +coding-context implement-feature +``` + +It's equivalent to: +```bash +coding-context -s languages=go -s stage=implementation implement-feature +``` + +--- + +## Resume Mode + +Continue work without re-sending all rules: + +**Initial invocation:** +```bash +coding-context fix-bug | ai-agent +# Includes all rules + initial task +``` + +**Resume invocation:** +```bash +coding-context -r fix-bug | ai-agent +# Skips rules, uses resume-specific task +``` + +**Task files:** +- `fix-bug-initial.md` with `resume: false` +- `fix-bug-resume.md` with `resume: true` + +**Saves tokens and reduces context size** + +--- + +## Targeting Specific Agents + +Exclude agent-specific paths (agent reads them itself): + +```bash +# Using with Cursor +coding-context -a cursor fix-bug +# Excludes: .cursor/rules, .cursorrules +# Includes: .github/agents, .agents/rules, etc. + +# Using with GitHub Copilot +coding-context -a copilot implement-feature +# Excludes: .github/copilot-instructions.md, .github/agents +# Includes: .cursor/rules, .agents/rules, etc. +``` + +**Avoids duplication** while including cross-agent rules + +--- + +## Agentic Workflows Integration + +Perfect for autonomous AI workflows: + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Agentic Workflow Ecosystem โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Context Layer โ”‚โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บโ”‚ Execution Layer โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ +โ”‚ โ”‚ Coding Context โ”‚ โ”‚ GitHub Actions โ”‚ โ”‚ +โ”‚ โ”‚ CLI โ”‚ โ”‚ (Agentic Workflows) โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Rules โ”‚ โ”‚ โ€ข Workflow def โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Guidelines โ”‚ โ”‚ โ€ข Step execution โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Tasks โ”‚ โ”‚ โ€ข Tool calling โ”‚ โ”‚ +โ”‚ โ”‚ โ€ข Parameters โ”‚ โ”‚ โ€ข State mgmt โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## GitHub Actions Integration + +Use in CI/CD workflows: + +```yaml +name: Agentic Code Review +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Assemble Context + run: | + coding-context \ + -s task=code-review \ + -p pr_number=${{ github.event.pull_request.number }} \ + code-review > context.txt + + - name: Execute AI Review + uses: github/agent-action@v1 + with: + context-file: context.txt +``` + +--- + +## Multi-Stage Workflows + +Different context for different stages: + +```yaml +jobs: + plan: + steps: + - name: Planning Context + run: coding-context -s stage=planning plan-feature > plan.txt + + implement: + steps: + - name: Implementation Context + run: coding-context -s stage=implementation implement > impl.txt + + test: + steps: + - name: Testing Context + run: coding-context -s stage=testing test-feature > test.txt +``` + +--- + +## Best Practices + +1. **Version Control Your Rules** + - Store `.agents/rules` and `.agents/tasks` in Git + - Track changes to context over time + +2. **Use Selectors Strategically** + - Filter by language, stage, priority + - Keep context relevant and focused + +3. **Parameterize Task Prompts** + - Use `-p` for runtime values + - Make tasks reusable + +4. **Organize by Concern** + - Separate planning, implementation, validation + - Use frontmatter to categorize + +--- + +## Best Practices (continued) + +5. **Use Bootstrap Scripts** + - Fetch real-time data (Jira, GitHub) + - Install required tools + - Prepare environment + +6. **Monitor Token Count** + - Tool reports token estimates to stderr + - Stay within model limits + - Optimize rule selection + +7. **Share Team Rules** + - Use remote directories (`-d` flag) + - Maintain organization-wide standards + - Version control shared rules + +--- + +## Example: Multi-Language Project + +**Project structure:** +``` +.agents/ +โ”œโ”€โ”€ rules/ +โ”‚ โ”œโ”€โ”€ go-standards.md (languages: [go]) +โ”‚ โ”œโ”€โ”€ python-standards.md (languages: [python]) +โ”‚ โ”œโ”€โ”€ js-standards.md (languages: [javascript]) +โ”‚ โ””โ”€โ”€ testing.md (stage: testing) +โ””โ”€โ”€ tasks/ + โ”œโ”€โ”€ fix-bug.md + โ””โ”€โ”€ implement-feature.md +``` + +**Usage:** +```bash +# Work on Go code +coding-context -s languages=go fix-bug + +# Work on Python code +coding-context -s languages=python implement-feature +``` + +--- + +## Example: Remote Rules Repository + +**Scenario:** Company maintains shared coding standards + +```bash +# Use company-wide rules +coding-context \ + -d git::https://github.com/company/coding-standards.git \ + -s languages=go \ + implement-feature | ai-agent + +# Mix local and remote +coding-context \ + -d git::https://github.com/company/standards.git \ + -d https://team.company.com/guidelines \ + -s priority=high \ + fix-bug | ai-agent +``` + +**Benefits:** Centralized, versioned, reusable + +--- + +## Real-World Use Cases + +๐Ÿ› **Bug Triage & Fixing** +```bash +coding-context -p issue=BUG-123 -s languages=go fix-bug +``` + +โœจ **Feature Implementation** +```bash +coding-context -s stage=implementation implement-feature +``` + +๐Ÿ” **Code Review** +```bash +coding-context -p pr_number=456 code-review +``` + +๐Ÿ“ **Documentation Updates** +```bash +coding-context -s type=documentation update-docs +``` + +--- + +## Real-World Use Cases (continued) + +๐Ÿš€ **Deployment Tasks** +```bash +coding-context -s environment=production -p version=1.2.3 deploy +``` + +๐Ÿ”ง **Refactoring** +```bash +coding-context -s languages=java -p module=auth refactor +``` + +๐Ÿงช **Test Writing** +```bash +coding-context -s stage=testing -s languages=python write-tests +``` + +โšก **Performance Optimization** +```bash +coding-context -s priority=high optimize-performance +``` + +--- + +## Token Estimation + +Tool provides real-time token estimates: + +```bash +$ coding-context -s languages=go fix-bug > context.txt +[INFO] Processing rules... +[INFO] Token estimate: ~2,450 tokens +[INFO] Task: fix-bug (~500 tokens) +[INFO] Total estimate: ~2,950 tokens +``` + +**Helps you:** +- Stay within model limits (GPT-4: 8K-128K, Claude: 200K) +- Optimize rule selection +- Monitor context growth + +--- + +## Security & Privacy + +โœ… **Single-pass expansion** prevents injection attacks +โœ… **Bootstrap output** goes to stderr (not AI context) +โœ… **No secrets** in version-controlled rules +โœ… **Local execution** - data stays on your machine + +**Best practices:** +- Use environment variables for secrets +- Keep sensitive data in bootstrap scripts +- Review generated context before sending to AI + +--- + +## Language Support + +Common languages supported through selectors: + +**Frontend:** `javascript`, `typescript`, `html`, `css`, `dart` + +**Backend:** `go`, `java`, `python`, `ruby`, `rust`, `csharp`, `php` + +**Mobile:** `swift`, `kotlin`, `objectivec`, `dart` + +**Other:** `shell`, `yaml`, `markdown`, `scala`, `elixir`, `haskell` + +**Note:** Use lowercase in frontmatter and selectors + +--- + +## Project Structure Example + +``` +my-project/ +โ”œโ”€โ”€ .agents/ +โ”‚ โ”œโ”€โ”€ rules/ +โ”‚ โ”‚ โ”œโ”€โ”€ go-standards.md +โ”‚ โ”‚ โ”œโ”€โ”€ testing.md +โ”‚ โ”‚ โ””โ”€โ”€ security.md +โ”‚ โ”œโ”€โ”€ tasks/ +โ”‚ โ”‚ โ”œโ”€โ”€ fix-bug.md +โ”‚ โ”‚ โ”œโ”€โ”€ implement-feature.md +โ”‚ โ”‚ โ””โ”€โ”€ code-review.md +โ”‚ โ””โ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ pre-deploy.md +โ”‚ โ””โ”€โ”€ post-deploy.md +โ”œโ”€โ”€ .github/ +โ”‚ โ””โ”€โ”€ copilot-instructions.md +โ””โ”€โ”€ CLAUDE.local.md +``` + +--- + +## Comparison with Alternatives + +| Feature | Coding Context CLI | Manual Context | Static Prompts | +|---------|-------------------|----------------|----------------| +| **Dynamic Assembly** | โœ… Automatic | โŒ Manual | โŒ Static | +| **Filtering** | โœ… Frontmatter | โŒ Copy-paste | โŒ None | +| **Parameterization** | โœ… CLI flags | โŒ Text edit | โŒ Hardcoded | +| **Reusability** | โœ… High | โŒ Low | โš ๏ธ Medium | +| **Team Sharing** | โœ… Git/Remote | โŒ Manual | โš ๏ธ Git | +| **Version Control** | โœ… Native | โŒ Manual | โœ… Native | +| **Token Optimization** | โœ… Automatic | โŒ Manual | โŒ None | + +--- + +## Getting Started (5 Steps) + +1. **Install the CLI** + ```bash + curl -fsL -o /usr/local/bin/coding-context + chmod +x /usr/local/bin/coding-context + ``` + +2. **Create rule file** (`.agents/rules/standards.md`) + ```markdown + # My Coding Standards + - Use meaningful names + - Write tests + ``` + +3. **Create task file** (`.agents/tasks/fix-bug.md`) + ```markdown + # Fix Bug: ${issue} + ``` + +--- + +## Getting Started (continued) + +4. **Run the CLI** + ```bash + coding-context -p issue=123 fix-bug | llm -m claude-3-5-sonnet-20241022 + ``` + +5. **Iterate and refine** + - Add more rules + - Use selectors for filtering + - Parameterize tasks + - Share with team + +--- + +## Resources + +๐Ÿ“š **Documentation** +- [Full Documentation](https://kitproj.github.io/coding-context-cli/) +- [GitHub Repository](https://github.com/kitproj/coding-context-cli) + +๐Ÿ“– **Guides** +- [Getting Started Tutorial](https://kitproj.github.io/coding-context-cli/tutorials/getting-started) +- [How-to Guides](https://kitproj.github.io/coding-context-cli/how-to/) + +๐Ÿ”— **Integration** +- [Agentic Workflows Guide](https://kitproj.github.io/coding-context-cli/explanation/agentic-workflows) +- [GitHub Actions Integration](https://kitproj.github.io/coding-context-cli/how-to/github-actions) + +--- + +## Community & Support + +๐Ÿ’ฌ **Get Help** +- [GitHub Issues](https://github.com/kitproj/coding-context-cli/issues) +- [Discussions](https://github.com/kitproj/coding-context-cli/discussions) + +๐Ÿค **Contribute** +- [Contributing Guide](https://github.com/kitproj/coding-context-cli/blob/main/CONTRIBUTING.md) +- Pull requests welcome! + +๐Ÿ“ **License** +- MIT License +- Free for personal and commercial use + +--- + +## Roadmap + +๐Ÿ”ฎ **Upcoming Features** + +- Enhanced token optimization +- Rule validation and linting +- Context caching for faster assembly +- More agent integrations +- AI-powered rule selection +- Workflow context injection +- Agent memory persistence + +**Follow the project for updates!** + +--- + +## Key Takeaways + +โœ… **Automate context assembly** for AI coding agents + +โœ… **Filter and optimize** with frontmatter selectors + +โœ… **Parameterize** task prompts for reusability + +โœ… **Share rules** via Git, HTTP, S3 + +โœ… **Integrate** with GitHub Actions and workflows + +โœ… **Support all major** AI coding agents + +โœ… **Open source** and extensible + +--- + + +# Thank You! + +**Coding Context CLI** + +Give AI agents the context they need to excel + +๐ŸŒ [kitproj.github.io/coding-context-cli](https://kitproj.github.io/coding-context-cli) +๐Ÿ’ป [github.com/kitproj/coding-context-cli](https://github.com/kitproj/coding-context-cli) + +**Questions?** + +--- + +## Appendix: Command Reference + +```bash +Usage: + coding-context [options] + +Options: + -C string + Change to directory before doing anything. (default ".") + -d value + Remote directory containing rules and tasks + -m string + Go Getter URL to a manifest file + -p value + Parameter to substitute (key=value) + -r Resume mode (skip rules) + -s value + Include rules with matching frontmatter (key=value) + -a string + Target agent (cursor, opencode, copilot, etc.) +``` + +--- + +## Appendix: Supported go-getter Protocols + +| Protocol | Example | Description | +|----------|---------|-------------| +| `http://` | `http://example.com/rules.tar.gz` | HTTP download | +| `https://` | `https://example.com/rules.tar.gz` | HTTPS download | +| `git::` | `git::https://github.com/user/repo.git` | Git clone | +| `s3::` | `s3::https://s3.amazonaws.com/bucket/path` | S3 bucket | +| `file://` | `file:///path/to/local/dir` | Local file path | + +See [go-getter docs](https://github.com/hashicorp/go-getter) for more + +--- + +## Appendix: File Extensions + +| Extension | Description | +|-----------|-------------| +| `.md` | Markdown rule or task file | +| `.mdc` | Markdown component (alternative extension) | +| `-bootstrap` | Executable bootstrap script (no extension) | + +**Examples:** +- `standards.md` - Rule file +- `fix-bug.md` - Task file +- `jira-bootstrap` - Bootstrap script diff --git a/SLIDES.pdf b/SLIDES.pdf new file mode 100644 index 00000000..9212e719 Binary files /dev/null and b/SLIDES.pdf differ diff --git a/SLIDES_README.md b/SLIDES_README.md new file mode 100644 index 00000000..c0e09403 --- /dev/null +++ b/SLIDES_README.md @@ -0,0 +1,258 @@ +# Coding Context CLI - Slide Deck + +This directory contains a presentation slide deck for the Coding Context CLI tool. + +## Files + +- **[SLIDES.md](./SLIDES.md)** - Main slide deck in Marp format +- **[SLIDES.pdf](./SLIDES.pdf)** - Pre-generated PDF (ready to use) + +## Viewing the Slides + +### Quick Start: Download the PDF + +The easiest way to view or present the slides is to download the pre-generated PDF: +- **[SLIDES.pdf](./SLIDES.pdf)** - Ready to open in any PDF viewer + +### Generate Your Own + +The slides are written in [Marp](https://marp.app/) markdown format. You have several options to generate or view them: + +### Option 1: Marp CLI (Recommended) + +Install Marp CLI globally: + +```bash +npm install -g @marp-team/marp-cli +``` + +Then view the slides in various formats: + +```bash +# View as HTML in browser +marp SLIDES.md -o slides.html && open slides.html + +# Export to PDF +marp SLIDES.md -o slides.pdf + +# Export to PowerPoint +marp SLIDES.md -o slides.pptx + +# Watch mode (auto-reload on changes) +marp -w SLIDES.md +``` + +### Option 2: Marp for VS Code + +1. Install the [Marp for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) extension +2. Open `SLIDES.md` in VS Code +3. Click the preview icon or press `Ctrl+K V` (Windows/Linux) or `Cmd+K V` (macOS) +4. Use the export function to save as HTML, PDF, or PowerPoint + +### Option 3: Online Viewer + +Use the Marp Web interface: +1. Go to https://web.marp.app/ +2. Copy the contents of `SLIDES.md` +3. Paste into the editor +4. View and export + +### Option 4: Docker + +If you have Docker installed: + +```bash +# Export to HTML +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.html + +# Export to PDF +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.pdf + +# Export to PowerPoint +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.pptx +``` + +## Presenting + +### Keyboard Shortcuts (HTML output) + +When viewing the HTML version in a browser: + +- **Arrow keys** / **Space** / **Page Up/Down** - Navigate slides +- **F** - Fullscreen mode +- **Esc** - Exit fullscreen +- **?** - Show keyboard shortcuts + +### Presenter Notes + +To add presenter notes (not visible in slides): + +```markdown +--- + +## Slide Title + +Slide content here + + + +--- +``` + +## Customizing the Slides + +### Themes + +Change the theme by modifying the frontmatter at the top of `SLIDES.md`: + +```yaml +--- +marp: true +theme: default # Options: default, gaia, uncover +--- +``` + +### Custom Styles + +The slides include custom CSS in the frontmatter. Modify the `style:` section to change colors, fonts, or layout: + +```yaml +style: | + section { + font-size: 28px; + } + h1 { + color: #2c3e50; + } +``` + +### Page Classes + +Apply different layouts to specific slides: + +```markdown +--- + + +# Centered Title Slide + +--- + + +# Dark Background Slide + +--- +``` + +## Export Formats + +### HTML + +Best for: +- Web hosting +- Interactive viewing +- Easy sharing via URL + +```bash +marp SLIDES.md -o slides.html +``` + +### PDF + +Best for: +- Printing +- Offline distribution +- Universal compatibility + +```bash +marp SLIDES.md -o slides.pdf +``` + +### PowerPoint (PPTX) + +Best for: +- Further editing in PowerPoint/Keynote +- Corporate environments +- Adding animations + +```bash +marp SLIDES.md -o slides.pptx +``` + +## Hosting the Slides + +### GitHub Pages + +Add to your repository's GitHub Pages: + +```bash +marp SLIDES.md -o docs/slides.html +git add docs/slides.html +git commit -m "Add slide deck" +git push +``` + +Access at: `https://.github.io//slides.html` + +### Self-Hosted + +Upload the HTML file to any web server: + +```bash +marp SLIDES.md -o index.html +# Upload index.html to your server +``` + +## Slide Deck Contents + +The slide deck covers: + +1. **Introduction** - Problem statement and solution +2. **Key Features** - Dynamic assembly, rules, tasks, remote directories +3. **Installation** - Quick setup for Linux and macOS +4. **Usage** - Basic commands and examples +5. **Advanced Features** - Selectors, bootstrap scripts, expansion +6. **Integration** - AI agents, GitHub Actions, agentic workflows +7. **Best Practices** - Tips for effective usage +8. **Examples** - Real-world use cases +9. **Resources** - Documentation and community links + +## Tips for Presenting + +1. **Practice navigation** - Familiarize yourself with the slide flow +2. **Prepare demos** - Have terminal windows ready for live demonstrations +3. **Know your audience** - Adjust depth based on technical level +4. **Use examples** - Refer to the example sections when questions arise +5. **Share resources** - Point to documentation links at the end + +## Updating the Slides + +When making changes: + +1. Edit `SLIDES.md` +2. Test locally: `marp SLIDES.md -o test.html && open test.html` +3. Commit changes to version control +4. Re-export in desired formats + +## License + +The slide deck is part of the Coding Context CLI project and is licensed under the MIT License. + +## Contributing + +To suggest improvements to the slides: + +1. Fork the repository +2. Edit `SLIDES.md` +3. Test your changes with Marp +4. Submit a pull request + +## Resources + +- [Marp Documentation](https://marpit.marp.app/) +- [Marp CLI](https://github.com/marp-team/marp-cli) +- [Marp for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) +- [Coding Context CLI Documentation](https://kitproj.github.io/coding-context-cli/) diff --git a/examples/PRESENTATION.md b/examples/PRESENTATION.md new file mode 100644 index 00000000..4c80e57a --- /dev/null +++ b/examples/PRESENTATION.md @@ -0,0 +1,226 @@ +# Presentation Example + +This example demonstrates how to use the slide deck for presentations about the Coding Context CLI. + +## Quick Start + +The main slide deck is available in two formats: +- [`../SLIDES.md`](../SLIDES.md) - Marp markdown format (editable) +- [`../SLIDES.pdf`](../SLIDES.pdf) - Pre-generated PDF (ready to use) + +**For immediate use:** Download and open [`SLIDES.pdf`](../SLIDES.pdf) in any PDF viewer. + +## Viewing Options + +### 1. PDF Viewer (Easiest) + +Simply open [`../SLIDES.pdf`](../SLIDES.pdf) in any PDF viewer: +- Adobe Acrobat Reader +- Preview (macOS) +- Edge, Chrome, or Firefox +- Your system's default PDF viewer + +### 2. VS Code (For Editing) + +1. Install the [Marp for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) extension +2. Open `SLIDES.md` in VS Code +3. Press `Ctrl+K V` (Windows/Linux) or `Cmd+K V` (macOS) to open preview +4. Use the export button to generate HTML, PDF, or PowerPoint + +### 3. Command Line + +```bash +# Install Marp CLI +npm install -g @marp-team/marp-cli + +# Generate HTML +marp SLIDES.md -o slides.html + +# Generate PDF +marp SLIDES.md -o slides.pdf + +# Generate PowerPoint +marp SLIDES.md -o slides.pptx + +# Watch mode (auto-reload) +marp -w SLIDES.md +``` + +### 4. Docker + +```bash +# HTML +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.html + +# PDF +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.pdf + +# PowerPoint +docker run --rm -v $PWD:/home/marp/app/ -e LANG=en_US.UTF-8 marpteam/marp-cli SLIDES.md -o slides.pptx +``` + +## Presentation Scenarios + +### Scenario 1: Quick Demo (5 minutes) + +Focus on these slides: +- Slide 1-2: Introduction and Problem +- Slide 3-4: Solution and Key Features +- Slide 8: Installation +- Slide 9-10: Basic Usage and Examples +- Slide 50: Resources + +**Demo commands:** +```bash +# Simple example +coding-context fix-bug | llm -m claude-3-5-sonnet-20241022 + +# With parameters +coding-context -p issue=BUG-123 -s languages=go fix-bug +``` + +### Scenario 2: Technical Deep Dive (15 minutes) + +Cover these sections: +- Slides 1-7: Introduction and Features +- Slides 8-16: Installation and Usage +- Slides 17-28: Rule Files, Tasks, and Advanced Features +- Slides 35-42: Best Practices and Examples +- Slide 50: Resources + +**Demo commands:** +```bash +# Show rule discovery +coding-context -s languages=go fix-bug | head -50 + +# Show with selectors +coding-context -s languages=go -s stage=implementation implement-feature + +# Show remote rules +coding-context -d git::https://github.com/company/rules.git fix-bug +``` + +### Scenario 3: Full Workshop (30-45 minutes) + +Use the entire slide deck with hands-on exercises: + +1. **Introduction** (5 min) - Slides 1-7 +2. **Installation** (5 min) - Slides 8-9 + hands-on +3. **Basic Usage** (10 min) - Slides 10-16 + demos +4. **Advanced Features** (10 min) - Slides 17-28 + demos +5. **Integration** (5 min) - Slides 29-34 +6. **Best Practices** (5 min) - Slides 35-42 +7. **Q&A** (5-10 min) + +**Hands-on exercises:** + +```bash +# Exercise 1: Create a simple rule +mkdir -p .agents/rules +cat > .agents/rules/testing.md << 'EOF' +--- +stage: testing +--- +# Testing Standards +- Write unit tests for all new code +- Aim for >80% coverage +EOF + +# Exercise 2: Create a task +mkdir -p .agents/tasks +cat > .agents/tasks/write-tests.md << 'EOF' +--- +selectors: + stage: testing +--- +# Write Tests for ${module} + +Create comprehensive unit tests. +EOF + +# Exercise 3: Run the CLI +coding-context -s stage=testing -p module=auth write-tests + +# Exercise 4: Try with remote rules +coding-context -d git::https://github.com/kitproj/coding-context-cli.git//examples/agents/rules write-tests +``` + +## Customizing for Your Audience + +### For Developers + +Emphasize: +- Technical implementation (slides 17-28) +- CLI usage and options (slides 9-16) +- Integration examples (slides 35-42) +- Code examples and demos + +### For Managers/Leadership + +Emphasize: +- Problem statement (slides 1-2) +- Business benefits (slides 3-7) +- Team collaboration features (slides 24, 35-42) +- Workflow integration (slides 29-34) + +### For DevOps/SRE + +Emphasize: +- GitHub Actions integration (slide 30-32) +- Remote directories (slide 24) +- Bootstrap scripts (slide 25) +- Agentic workflows (slides 29-34) + +## Presentation Tips + +1. **Prepare Your Environment** + ```bash + # Have these ready in terminal windows + cd /path/to/demo/project + coding-context --help + ls -la .agents/ + ``` + +2. **Use Real Examples** + - Show actual rule files from your project + - Demonstrate with real task scenarios + - Use familiar tech stack in examples + +3. **Interactive Demos** + - Let audience suggest selector values + - Show token counts in real-time + - Demonstrate different AI agents + +4. **Common Questions** + - Q: "Can we use with our existing CI/CD?" + A: Yes! Show slide 30 (GitHub Actions integration) + + - Q: "How do we share rules across teams?" + A: Show slide 24 (Remote Directories) + + - Q: "What about security?" + A: Show slide 44 (Security & Privacy) + +## After the Presentation + +Share these resources with attendees: + +- **Documentation**: https://kitproj.github.io/coding-context-cli/ +- **GitHub Repo**: https://github.com/kitproj/coding-context-cli +- **Slide Deck**: Available in the repository at `SLIDES.md` +- **Getting Started Guide**: https://kitproj.github.io/coding-context-cli/tutorials/getting-started + +## Feedback + +After presenting, consider: +- Collecting feedback on which topics resonated +- Noting questions for FAQ additions +- Updating examples based on audience interests +- Contributing improvements back to the slide deck + +## Additional Resources + +- [Full documentation](https://kitproj.github.io/coding-context-cli/) +- [SLIDES_README.md](../SLIDES_README.md) - Detailed viewing instructions +- [AGENTIC_WORKFLOWS.md](../AGENTIC_WORKFLOWS.md) - Workflow integration guide +- [Examples directory](./agents/) - Sample rules and tasks