ragtime-cli 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

src/commands/create-pr.md

@@ -0,0 +1,389 @@
+---
+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

@@ -0,0 +1,325 @@
+---
+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
+```

src/commands/pr-graduate.md

@@ -1,9 +1,14 @@
 ---
-description: Graduate branch knowledge to app after PR merge
+description: Graduate branch knowledge to app after PR merge (fallback)
 allowed-tools: Bash, mcp__ragtime__search, mcp__ragtime__graduate, mcp__ragtime__update_status, mcp__ragtime__remember, AskUserQuestion
 ---
 
-# PR Graduate: Curate Branch Knowledge
+# PR Graduate: Curate Branch Knowledge (Post-Merge)
+
+> **Preferred workflow:** Use `/create-pr` instead - it graduates memories *before*
+> creating the PR so knowledge is committed alongside code.
+>
+> Use this command only if you already merged without graduating.
 
 After a PR is merged, review branch memories and decide what becomes permanent app knowledge.