ragtime-cli 0.2.17__py3-none-any.whl → 0.3.0__py3-none-any.whl

src/commands/create-pr.md

@@ -1,389 +0,0 @@
----
-description: Create a PR with convention checks and graduated knowledge
-allowed-arguments: optional PR title
-allowed-tools: Bash, Read, Write, Edit, AskUserQuestion, mcp__ragtime__search, mcp__ragtime__memories
----
-
-# Create PR
-
-Create a pull request with branch knowledge graduated and committed alongside the code.
-
-**Usage:**
-- `/create-pr` - Interactive PR creation with memory curation
-- `/create-pr "Add authentication flow"` - With suggested title
-
-## Overview
-
-This command ensures code follows team standards and knowledge gets merged with the code:
-
-1. Check code against team conventions and app patterns
-2. Review branch memories and decide what graduates to `app/`
-3. Check for conflicts with existing app knowledge
-4. Commit graduated memories as part of the PR
-5. Create the pull request
-
-## Step 1: Gather Context
-
-```bash
-BRANCH=$(git branch --show-current)
-BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
-
-echo "Branch: $BRANCH"
-
-# Check for uncommitted changes
-git status --short
-
-# Get commits on this branch
-git log main..HEAD --oneline
-```
-
-## Step 2: Check Code Against Team Conventions
-
-Before creating the PR, verify the code follows team standards.
-
-### Load conventions config
-
-Check `.ragtime/config.yaml` for conventions settings:
-
-```yaml
-# Default config (if not specified):
-conventions:
-  files:
-    - ".ragtime/CONVENTIONS.md"
-  also_search_memories: true
-```
-
-### Read conventions files
-
-For each file in `conventions.files`, read it if it exists:
-
-```bash
-# Check for conventions files
-cat .ragtime/CONVENTIONS.md 2>/dev/null
-# Or other configured files like docs/CODING_STANDARDS.md
-```
-
-The conventions doc should contain clear, checkable rules like:
-- "All API endpoints must use auth middleware"
-- "Use async/await, not .then() chains"
-- "Never commit .env files"
-
-### Also search memories (if enabled)
-
-If `also_search_memories: true` (default), also search for convention memories:
-
-```
-mcp__ragtime__search:
-  query: "convention standard pattern rule always never"
-  namespace: "team"
-  limit: 20
-```
-
-```
-mcp__ragtime__search:
-  query: "pattern architecture convention"
-  namespace: "app"
-  type: "convention,pattern"
-  limit: 20
-```
-
-### Get changed files
-
-```bash
-# Files changed in this branch
-git diff --name-only main...HEAD
-```
-
-### Review code against conventions
-
-For each relevant convention/pattern found, check if the changed code follows it:
-
-1. Read the convention/pattern memory
-2. Read the relevant changed files
-3. Check for compliance
-
-Present findings:
-
-```
-───────────────────────────────────────────
-🔍 CONVENTION CHECK
-───────────────────────────────────────────
-
-Checked {file_count} changed files against {convention_count} team conventions.
-
-✅ PASSING:
-- "Use async/await, not .then()" - All async code uses await
-- "Error responses use ApiError class" - Verified in api/routes.ts
-
-⚠️ POTENTIAL ISSUES:
-- "All API endpoints need auth middleware"
-  → src/api/newEndpoint.ts:15 - No auth middleware detected
-
-- "Use logger.error(), not console.error()"
-  → src/services/auth.ts:42 - Found console.error()
-
-❌ VIOLATIONS:
-- "Never commit .env files"
-  → .env.local is staged
-───────────────────────────────────────────
-```
-
-### Handle issues
-
-If issues found:
-
-```
-Found {issue_count} potential issues.
-
-Options:
-1. **Fix now** - I'll help fix these before creating PR
-2. **Ignore** - Create PR anyway (add justification comment)
-3. **Review each** - Go through issues one by one
-4. **Cancel** - Fix manually and try again
-```
-
-If "Fix now": Help the user fix each issue before proceeding.
-
-If "Ignore": Ask for justification to include in PR description.
-
-**Only proceed to memory curation after issues are resolved or acknowledged.**
-
-## Step 3: Check for Branch Memories
-
-Search for memories in this branch's namespace:
-
-```bash
-# Check .ragtime/branches/{branch-slug}/ for memory files
-ls -la .ragtime/branches/$BRANCH_SLUG/ 2>/dev/null || echo "No branch memories found"
-```
-
-Also search the index:
-
-```
-mcp__ragtime__search:
-  query: "*"
-  namespace: "branch-{branch-slug}"
-  limit: 50
-```
-
-**If no branch memories found:** Skip to Step 8 (Create PR).
-
-**If memories found:** Continue to Step 4.
-
-## Step 4: Present Memories for Curation
-
-```
-───────────────────────────────────────────
-📋 BRANCH KNOWLEDGE REVIEW
-───────────────────────────────────────────
-
-Before creating the PR, let's review knowledge from this branch.
-
-Graduated memories will be:
-- Moved to app/ or team/ namespace
-- Committed as part of this PR
-- Merged with your code changes
-
-Found {count} memories in branch-{branch}:
-
-───────────────────────────────────────────
-```
-
-For each memory, show:
-
-```
-**Memory {n} of {count}:**
-
-"{content preview - first 150 chars}..."
-
-Type: {type} | Component: {component}
-File: {relative_path}
-
-Action?
-1. ✅ Graduate to app/
-2. 🏛️ Graduate to team/ (conventions/standards)
-3. 📚 Keep in branch (don't include in PR)
-4. ❌ Abandon (mark as noise)
-5. 👀 Show full content
-```
-
-## Step 5: Check for Conflicts
-
-For each memory being graduated, search for similar content in app/:
-
-```
-mcp__ragtime__search:
-  query: "{memory content keywords}"
-  namespace: "app"
-  limit: 5
-```
-
-If similar memories exist (similarity > 0.8), present:
-
-```
-⚠️ POTENTIAL CONFLICT
-
-Graduating: "{new memory preview}..."
-
-Similar existing memory in app/:
-"{existing memory preview}..."
-File: {existing_file}
-
-Options:
-1. **Keep both** - They're different enough
-2. **Replace existing** - New one is better/more current
-3. **Merge** - Combine into one comprehensive memory
-4. **Skip graduation** - Existing one is sufficient
-```
-
-### If merging:
-
-Ask the user to provide the merged content, or offer to draft it:
-
-```
-I can draft a merged version combining both. Want me to try?
-```
-
-If yes, present the draft for approval before saving.
-
-## Step 6: Execute Graduation
-
-For each memory to graduate:
-
-### Move the file
-
-```bash
-# From: .ragtime/branches/{branch-slug}/{id}-{slug}.md
-# To:   .ragtime/app/{component}/{id}-{slug}.md (or .ragtime/team/)
-
-mkdir -p .ragtime/app/{component}
-mv .ragtime/branches/{branch-slug}/{id}-{slug}.md .ragtime/app/{component}/
-```
-
-### Update the frontmatter
-
-Edit the file to update:
-- `namespace: app` (or `team`)
-- `confidence: high`
-- `confidence_reason: pr-graduate`
-- `source: pr-graduate`
-- Add `graduated_from: branch-{branch}`
-
-### Stage the changes
-
-```bash
-git add .ragtime/app/
-git add .ragtime/team/
-# Don't stage branch/ folder - it stays local or gets cleaned up later
-```
-
-## Step 7: Commit Knowledge (if any graduated)
-
-If memories were graduated:
-
-```bash
-git add .ragtime/app/ .ragtime/team/
-
-git commit -m "docs: graduate branch knowledge to app
-
-Graduated {count} memories from branch-{branch}:
-- {memory1 summary}
-- {memory2 summary}
-..."
-```
-
-## Step 8: Create the PR
-
-```bash
-# Check if we need to push
-git push -u origin $BRANCH 2>/dev/null || git push
-
-# Create PR
-gh pr create --title "{title}" --body "$(cat <<'EOF'
-## Summary
-
-{summary from commits and context}
-
-## Convention Compliance
-
-{if all passed}
-✅ All team conventions verified
-
-{if issues were acknowledged}
-⚠️ Known deviations:
-- {issue}: {justification}
-
-## Knowledge Added
-
-{if memories were graduated}
-This PR includes {count} graduated memories:
-- {list of graduated memories with types}
-
-## Test Plan
-
-- [ ] {test items}
-
----
-🤖 Generated with [Claude Code](https://claude.ai/code)
-EOF
-)"
-```
-
-## Step 9: Summary
-
-```
-───────────────────────────────────────────
-✅ PR CREATED
-───────────────────────────────────────────
-
-PR: {url}
-Branch: {branch}
-
-Knowledge graduated: {count}
-  → app/: {app_count}
-  → team/: {team_count}
-
-Remaining in branch/: {kept_count}
-Abandoned: {abandoned_count}
-
-The graduated knowledge is now part of your PR.
-Reviewers will see it alongside your code changes.
-```
-
-## Quick Mode
-
-For branches with few memories, offer quick mode:
-
-```
-Found {count} branch memories.
-
-1. **Review each** - Curate one by one
-2. **Quick mode** - I'll propose what to graduate
-3. **Graduate all to app/** - Promote everything
-4. **Skip knowledge** - Create PR without graduating
-```
-
-Quick mode analyzes content and proposes:
-
-```
-## Quick Mode Proposal
-
-**Graduate to app/:**
-- "Auth uses JWT with 15-min expiry" (architecture)
-- "Redis chosen for session storage" (decision)
-
-**Keep in branch:**
-- "Debug notes: token refresh" (task-state)
-
-**Abandon:**
-- "TODO: fix later" (noise)
-
-Approve this? (yes / review each / edit)
-```
-
-## Notes
-
-- Graduated memories are committed as part of the PR, so reviewers see them
-- Branch memories that aren't graduated stay in `.ragtime/branches/` for reference
-- After PR merges, run `ragtime prune` to clean up synced branch folders
-- The old `/pr-graduate` command can still be used if you forget to graduate before PR

src/commands/generate-docs.md

@@ -1,325 +0,0 @@
----
-description: Generate documentation from code with AI analysis
-allowed-arguments: path to code (e.g., /generate-docs src/)
-allowed-tools: Bash, Read, Write, Edit, AskUserQuestion, Glob, Grep
----
-
-# Generate Docs
-
-Analyze code and generate comprehensive documentation.
-
-**Usage:**
-- `/generate-docs src/` - Generate docs for src folder
-- `/generate-docs src/auth/` - Document specific module
-- `/generate-docs` - Interactive mode
-
-## Overview
-
-You (Claude) will:
-1. Read and understand the code
-2. Write clear, helpful documentation
-3. Include examples and usage notes
-4. Output as markdown files
-
-This is the AI-powered version. For quick stubs without AI, use `ragtime generate --stubs`.
-
-## Step 1: Get the Code Path
-
-**If `$ARGUMENTS` provided:**
-- Use it as the code path
-
-**If no arguments:**
-- Ask: "What code should I document? (e.g., src/, src/auth/, specific file)"
-
-## Step 2: Discover Code Files
-
-```bash
-# Find code files
-find {path} -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) \
-  -not -path "*/__pycache__/*" \
-  -not -path "*/node_modules/*" \
-  -not -path "*/.venv/*"
-```
-
-If many files found, ask:
-```
-Found {count} files. Options:
-
-1. Document all
-2. Document specific folder
-3. Document specific files (I'll list them)
-```
-
-## Step 3: Choose Output Location
-
-```
-Where should I save the documentation?
-
-1. **docs/api/** - API reference docs
-2. **docs/code/** - Code documentation
-3. **.ragtime/app/** - As searchable memories
-4. **Custom path**
-```
-
-## Step 4: Analyze and Document Each File
-
-For each code file:
-
-1. **Read the full file**
-2. **Understand what it does** - purpose, patterns, relationships
-3. **Write documentation** that explains:
-   - What the module/class/function does
-   - Why it exists (context)
-   - How to use it (examples)
-   - Important details (edge cases, requirements)
-
-### Documentation Quality Guidelines
-
-**Good documentation answers:**
-- What does this do?
-- Why would I use it?
-- How do I use it?
-- What should I watch out for?
-
-**Avoid:**
-- Just restating the function name ("getUserById gets a user by ID")
-- Obvious descriptions
-- Missing the "why"
-
-### Documentation Template
-
-```markdown
-# {Module Name}
-
-> **File:** `{path}`
-
-## Overview
-
-{2-3 sentences explaining what this module does and why it exists}
-
-## Quick Start
-
-\`\`\`{language}
-{Simple usage example}
-\`\`\`
-
----
-
-## API Reference
-
-### `ClassName`
-
-{Description of the class - what it represents, when to use it}
-
-#### Constructor
-
-\`\`\`{language}
-{constructor signature}
-\`\`\`
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `param` | `Type` | {Actual description} |
-
-#### Methods
-
-##### `methodName(params) -> ReturnType`
-
-{What this method does, not just restating the name}
-
-**Parameters:**
-- `param` (`Type`): {Description}
-
-**Returns:** {What it returns and when}
-
-**Example:**
-\`\`\`{language}
-{Practical example}
-\`\`\`
-
-**Notes:**
-- {Important edge cases}
-- {Performance considerations}
-- {Related methods}
-
----
-
-## Functions
-
-### `functionName(params) -> ReturnType`
-
-{Description}
-
-{Parameters, returns, example - same format as methods}
-
----
-
-## Constants / Configuration
-
-| Name | Value | Description |
-|------|-------|-------------|
-| `CONSTANT` | `value` | {What it's for} |
-
----
-
-## See Also
-
-- [{Related Module}]({link})
-- [{External Docs}]({link})
-```
-
-## Step 5: Add Frontmatter (if .ragtime/ output)
-
-```yaml
----
-namespace: app
-type: architecture
-component: {from path}
-source: generate-docs
-confidence: medium
-confidence_reason: ai-generated
----
-```
-
-## Step 6: Write and Report
-
-```
-Generating documentation...
-
-  ✓ src/auth/jwt.py → docs/api/auth/jwt.md
-    - JWTManager class
-    - create_token, validate_token functions
-
-  ✓ src/auth/sessions.py → docs/api/auth/sessions.md
-    - SessionStore class
-    - Redis integration details
-
-  ✓ src/db/models.py → docs/api/db/models.md
-    - User, Claim, Shift models
-    - Relationships documented
-```
-
-## Step 7: Summary
-
-```
-───────────────────────────────────────────
-✅ DOCUMENTATION COMPLETE
-───────────────────────────────────────────
-
-Generated {count} documentation files
-
-Coverage:
-  - {n} classes documented
-  - {n} functions documented
-  - {n} with examples
-
-Output: {output_path}/
-
-Next steps:
-  - Review the generated docs
-  - Add any missing context
-  - Run 'ragtime index' to make searchable
-```
-
-## Best Practices
-
-When writing docs:
-
-1. **Start with the "why"** - Don't just describe what, explain purpose
-2. **Include real examples** - Show actual usage, not abstract patterns
-3. **Document edge cases** - What happens with null? Empty arrays?
-4. **Link related concepts** - Help readers navigate
-5. **Keep it scannable** - Use headers, tables, code blocks
-
-## Example
-
-For this code:
-
-```python
-class RateLimiter:
-    """Rate limiting using token bucket algorithm."""
-
-    def __init__(self, requests_per_minute: int = 60):
-        self.rpm = requests_per_minute
-        self.tokens = requests_per_minute
-        self.last_update = time.time()
-
-    def allow(self, cost: int = 1) -> bool:
-        """Check if request is allowed, consuming tokens if so."""
-        self._refill()
-        if self.tokens >= cost:
-            self.tokens -= cost
-            return True
-        return False
-```
-
-Generate:
-
-```markdown
-# RateLimiter
-
-> **File:** `src/middleware/rate_limit.py`
-
-## Overview
-
-Implements rate limiting using the token bucket algorithm. Use this to protect
-APIs from abuse by limiting how many requests a client can make per minute.
-
-## Quick Start
-
-\`\`\`python
-limiter = RateLimiter(requests_per_minute=100)
-
-@app.before_request
-def check_rate_limit():
-    if not limiter.allow():
-        return {"error": "Rate limit exceeded"}, 429
-\`\`\`
-
----
-
-## API Reference
-
-### `RateLimiter`
-
-A token bucket rate limiter. Tokens refill continuously over time, allowing
-for burst traffic while maintaining an average rate limit.
-
-#### Constructor
-
-\`\`\`python
-RateLimiter(requests_per_minute: int = 60)
-\`\`\`
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `requests_per_minute` | `int` | `60` | Maximum requests allowed per minute |
-
-#### Methods
-
-##### `allow(cost: int = 1) -> bool`
-
-Check if a request should be allowed. If allowed, consumes tokens from the bucket.
-
-**Parameters:**
-- `cost` (`int`): Number of tokens this request costs. Use higher values for
-  expensive operations.
-
-**Returns:** `True` if the request is allowed, `False` if rate limited.
-
-**Example:**
-\`\`\`python
-# Normal request
-if limiter.allow():
-    process_request()
-
-# Expensive operation (costs 5 tokens)
-if limiter.allow(cost=5):
-    run_expensive_query()
-\`\`\`
-
-**Notes:**
-- Tokens refill continuously, not all at once
-- Thread-safe for single-process use
-- For distributed systems, use Redis-backed rate limiting instead
-```