ragtime-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{ragtime_cli-0.2.2/ragtime_cli.egg-info → ragtime_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragtime-cli"
-version = "0.2.2"
+version = "0.2.3"
 description = "Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge"
 readme = "README.md"
 license = "MIT"

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3/ragtime_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3}/ragtime_cli.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/db.py
 src/mcp_server.py
 src/memory.py
 src/commands/audit.md
+src/commands/create-pr.md
 src/commands/handoff.md
 src/commands/import-docs.md
 src/commands/pr-graduate.md

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3}/src/cli.py

@@ -166,7 +166,7 @@ def get_remote_branches_with_ragtime(path: Path) -> list[str]:
 
 
 @click.group()
-@click.version_option(version="0.2.2")
+@click.version_option(version="0.2.3")
 def main():
     """Ragtime - semantic search over code and documentation."""
     pass
@@ -206,11 +206,45 @@ index/
 """
     gitignore_path.write_text(gitignore_content)
 
+    # Create conventions file template
+    conventions_file = ragtime_dir / "CONVENTIONS.md"
+    if not conventions_file.exists():
+        conventions_file.write_text("""# Team Conventions
+
+Rules and patterns that code must follow. These are checked by `/create-pr`.
+
+## Code Style
+
+- [ ] Example: Use async/await, not .then() chains
+- [ ] Example: All API endpoints must use auth middleware
+
+## Architecture
+
+- [ ] Example: Services should not directly access repositories from other domains
+
+## Security
+
+- [ ] Example: Never commit .env or credentials files
+- [ ] Example: All user input must be validated
+
+## Testing
+
+- [ ] Example: All new features need unit tests
+
+---
+
+Add your team's conventions above. Each rule should be:
+- Clear and specific
+- Checkable against code
+- Actionable (what to do, not just what not to do)
+""")
+
     click.echo(f"\nCreated .ragtime/ structure:")
-    click.echo(f"  app/       - Graduated knowledge (tracked)")
-    click.echo(f"  team/      - Team conventions (tracked)")
-    click.echo(f"  branches/  - Active branches (yours tracked, synced gitignored)")
-    click.echo(f"  archive/   - Completed branches (tracked)")
+    click.echo(f"  app/           - Graduated knowledge (tracked)")
+    click.echo(f"  team/          - Team conventions (tracked)")
+    click.echo(f"  branches/      - Active branches (yours tracked, synced gitignored)")
+    click.echo(f"  archive/       - Completed branches (tracked)")
+    click.echo(f"  CONVENTIONS.md - Team rules checked by /create-pr")
 
     # Check for ghp-cli
     if check_ghp_installed():
@@ -362,6 +396,9 @@ def config(path: Path):
     click.echo(f"  Paths: {cfg.code.paths}")
     click.echo(f"  Languages: {cfg.code.languages}")
     click.echo(f"  Exclude: {cfg.code.exclude}")
+    click.echo("\nConventions:")
+    click.echo(f"  Files: {cfg.conventions.files}")
+    click.echo(f"  Also search memories: {cfg.conventions.also_search_memories}")
 
 
 # ============================================================================
@@ -709,21 +746,54 @@ def install_commands(global_install: bool, workspace_install: bool, list_command
     target_dir.mkdir(parents=True, exist_ok=True)
     commands_dir = get_commands_dir()
     installed = 0
+    skipped = 0
+    namespaced = 0
 
     for cmd in to_install:
         source = commands_dir / f"{cmd}.md"
         target = target_dir / f"{cmd}.md"
+        namespaced_target = target_dir / f"ragtime-{cmd}.md"
 
         if target.exists() and not force:
-            if click.confirm(f"  {cmd}.md exists. Overwrite?", default=False):
+            # Check if it's our file (contains ragtime marker)
+            existing_content = target.read_text()
+            is_ragtime_file = "ragtime" in existing_content.lower() and "mcp__ragtime" in existing_content
+
+            if is_ragtime_file:
+                # It's our file, safe to overwrite
                 target.write_text(source.read_text())
+                click.echo(f"  ✓ {cmd}.md (updated)")
                 installed += 1
+            else:
+                # Conflict with non-ragtime command
+                click.echo(f"\n⚠️  Conflict: {cmd}.md already exists (not a ragtime command)")
+                click.echo(f"   1. Overwrite with ragtime's version")
+                click.echo(f"   2. Skip (keep existing)")
+                click.echo(f"   3. Install as ragtime-{cmd}.md")
+
+                choice = click.prompt("   Choice", type=click.Choice(["1", "2", "3"]), default="2")
+
+                if choice == "1":
+                    target.write_text(source.read_text())
+                    click.echo(f"  ✓ {cmd}.md (overwritten)")
+                    installed += 1
+                elif choice == "2":
+                    click.echo(f"  • {cmd}.md (skipped)")
+                    skipped += 1
+                else:
+                    namespaced_target.write_text(source.read_text())
+                    click.echo(f"  ✓ ragtime-{cmd}.md")
+                    namespaced += 1
         else:
             target.write_text(source.read_text())
             click.echo(f"  ✓ {cmd}.md")
             installed += 1
 
     click.echo(f"\nInstalled {installed} commands to {target_dir}")
+    if namespaced:
+        click.echo(f"  ({namespaced} installed with ragtime- prefix)")
+    if skipped:
+        click.echo(f"  ({skipped} skipped due to conflicts)")
 
 
 @main.command("setup-ghp")
@@ -1300,7 +1370,7 @@ def update(check: bool):
     from urllib.request import urlopen
     from urllib.error import URLError
 
-    current = "0.2.2"
+    current = "0.2.3"
 
     click.echo(f"Current version: {current}")
     click.echo("Checking PyPI for updates...")

ragtime_cli-0.2.3/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

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3}/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.
 

{ragtime_cli-0.2.2 → ragtime_cli-0.2.3}/src/config.py

@@ -36,11 +36,19 @@ class CodeConfig:
     ])
 
 
+@dataclass
+class ConventionsConfig:
+    """Configuration for convention checking."""
+    files: list[str] = field(default_factory=lambda: [".ragtime/CONVENTIONS.md"])
+    also_search_memories: bool = True
+
+
 @dataclass
 class RagtimeConfig:
     """Main ragtime configuration."""
     docs: DocsConfig = field(default_factory=DocsConfig)
     code: CodeConfig = field(default_factory=CodeConfig)
+    conventions: ConventionsConfig = field(default_factory=ConventionsConfig)
 
     @classmethod
     def load(cls, project_path: Path) -> "RagtimeConfig":
@@ -58,6 +66,7 @@ class RagtimeConfig:
 
         docs_data = data.get("docs", {})
         code_data = data.get("code", {})
+        conventions_data = data.get("conventions", {})
 
         return cls(
             docs=DocsConfig(
@@ -70,6 +79,12 @@ class RagtimeConfig:
                 languages=code_data.get("languages", CodeConfig().languages),
                 exclude=code_data.get("exclude", CodeConfig().exclude),
             ),
+            conventions=ConventionsConfig(
+                files=conventions_data.get("files", ConventionsConfig().files),
+                also_search_memories=conventions_data.get(
+                    "also_search_memories", ConventionsConfig().also_search_memories
+                ),
+            ),
         )
 
     def save(self, project_path: Path) -> None:
@@ -89,6 +104,10 @@ class RagtimeConfig:
                 "languages": self.code.languages,
                 "exclude": self.code.exclude,
             },
+            "conventions": {
+                "files": self.conventions.files,
+                "also_search_memories": self.conventions.also_search_memories,
+            },
         }
 
         with open(config_path, "w") as f: