frankcode 0.1.0__tar.gz → 0.1.3__tar.gz

frankcode-0.1.3/.github/workflows/frankcode.yml

@@ -0,0 +1,26 @@
+name: FrankCode Issue Responder
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  frankcode-run:
+    # Only run on issue comments (not PRs) that contain '@frankcode'
+    if: ${{ !github.event.issue.pull_request && contains(github.event.comment.body, '@frankcode') }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run FrankCode Action
+        uses: joeyism/frankcode-action@main
+        with:
+          api-key: ${{ secrets.GEMINI_API_KEY }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}

frankcode-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI and GitHub Releases
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing
+      contents: write  # Mandatory for creating GitHub Releases
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+        
+    - name: Install build tools
+      run: python -m pip install --upgrade pip build
+      
+    - name: Build package
+      run: python -m build
+      
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: dist/*
+        generate_release_notes: true
+      
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

frankcode-0.1.3/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "master", "main" ]
+  pull_request:
+    branches: [ "master", "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest pytest-asyncio
+        pip install -e .
+        
+    - name: Run tests
+      run: |
+        pytest

frankcode-0.1.3/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.pycover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# opencode specific and frankcode runtime
+.frankcode/
+.opencode/
+logs/
+quarantine/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store

frankcode-0.1.3/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src/frankcode/configs *
+recursive-include src/frankcode/skills *

{frankcode-0.1.0/src/frankcode.egg-info → frankcode-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frankcode
-Version: 0.1.0
+Version: 0.1.3
 Summary: Advanced multi-agent orchestrator for OpenCode
 Author: joeyism
 License: MIT

{frankcode-0.1.0 → frankcode-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "frankcode"
-version = "0.1.0"
+dynamic = ["version"]
 description = "Advanced multi-agent orchestrator for OpenCode"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,9 +32,14 @@ Issues = "https://github.com/joeyism/frankcode/issues"
 frankcode = "frankcode.cli:app"
 
 [build-system]
-requires = ["setuptools>=61.0"]
+requires = ["setuptools>=61.0", "setuptools_scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools_scm]
+
+[tool.setuptools]
+include-package-data = true
+
 [tool.setuptools.package-data]
 frankcode = ["configs/*.json"]
 

frankcode-0.1.3/src/frankcode/cli.py

@@ -0,0 +1,163 @@
+import typer
+import asyncio
+import logging
+from typing import Optional
+from rich.console import Console
+from rich.logging import RichHandler
+
+from .environment import LocalEnvironment
+from .setup import FrankSetup
+from .orchestrator import FrankOrchestrator, resolve_nvm_path
+
+app = typer.Typer()
+console = Console()
+
+def setup_logging(verbose: bool):
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler(rich_tracebacks=True)]
+    )
+
+@app.command()
+def main(
+    prompt: str,
+    model: str = typer.Option("google/gemini-3.1-pro-preview", help="LLM model to use"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show debug logs"),
+    verify: bool = typer.Option(True, help="Enable verification and fix passes"),
+    clean: bool = typer.Option(False, help="Wipe .frankcode directory before starting"),
+    harbor_mode: bool = typer.Option(False, help="Exit with code 0 even if verification fails (for harbor compatibility)")
+):
+    setup_logging(verbose)
+    
+    if clean:
+        import shutil
+        import os
+        if os.path.exists(".frankcode"):
+            shutil.rmtree(".frankcode")
+
+    env = LocalEnvironment()
+    setup = FrankSetup(env, ".")
+    orchestrator = FrankOrchestrator(env, setup, model)
+
+    async def run():
+        # Step 0: Resolve NVM paths so npm/opencode are available
+        await resolve_nvm_path(env)
+
+        # Step 1: Install plugins and write configs
+        console.print("[bold blue]Installing safety plugins and generating configs...[/bold blue]")
+        await setup.ensure_directories()
+        await setup.install_plugins()
+        await setup.inject_plugins_into_system_configs()
+        
+        # Step 1.5: Seed bundled skills
+        await setup.install_skills()
+        
+        # Step 3: Run the task
+        console.print(f"[bold green]Executing task:[/bold green] {prompt}")
+        success = await orchestrator.run_task(prompt, verify=verify)
+        
+        if success:
+            console.print("[bold green]Task completed successfully![/bold green]")
+        else:
+            console.print("[bold red]Task failed to verify.[/bold red]")
+            if not harbor_mode:
+                raise typer.Exit(code=1)
+
+    asyncio.run(run())
+
+@app.command()
+def init_github():
+    """
+    Scaffold a GitHub Actions workflow file to run FrankCode on issue comments.
+    """
+    import os
+    workflow_dir = ".github/workflows"
+    os.makedirs(workflow_dir, exist_ok=True)
+    
+    workflow_path = os.path.join(workflow_dir, "frankcode.yml")
+    
+    workflow_content = """name: FrankCode Issue Responder
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  frankcode-run:
+    if: ${{ !github.event.issue.pull_request && contains(github.event.comment.body, '@frankcode') }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js (for OpenCode)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup Python (for FrankCode)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Dependencies
+        run: |
+          npm install -g opencode
+          pip install git+https://github.com/joeyism/frankcode-py.git
+
+      - name: Prepare Prompt
+        id: prompt
+        run: |
+          cat << 'EOF' > frankcode_prompt.txt
+          Please resolve the following issue.
+          
+          Title: ${{ github.event.issue.title }}
+          
+          Issue Description:
+          ${{ github.event.issue.body }}
+          
+          Instruction from comment:
+          ${{ github.event.comment.body }}
+          EOF
+
+      - name: Run FrankCode
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} 
+        run: |
+          frankcode "$(cat frankcode_prompt.txt)"
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "FrankCode: Implement fix for issue #${{ github.event.issue.number }}"
+          title: "FrankCode: Fix issue #${{ github.event.issue.number }} - ${{ github.event.issue.title }}"
+          body: |
+            This PR was generated by FrankCode in response to [Issue #${{ github.event.issue.number }}](${{ github.event.issue.html_url }}).
+            
+            Triggered by comment:
+            > ${{ github.event.comment.body }}
+          branch: "frankcode/issue-${{ github.event.issue.number }}"
+          base: ${{ github.event.repository.default_branch }}
+          labels: "frankcode, automated pr"
+          assignees: ${{ github.actor }}
+"""
+    if os.path.exists(workflow_path):
+        console.print(f"[yellow]Warning: {workflow_path} already exists. Skipping.[/yellow]")
+    else:
+        with open(workflow_path, "w") as f:
+            f.write(workflow_content)
+        console.print(f"[bold green]Successfully created {workflow_path}[/bold green]")
+        console.print("Make sure to add your [bold cyan]GEMINI_API_KEY[/bold cyan] to your repository's GitHub Actions secrets!")
+
+if __name__ == "__main__":
+    app()

{frankcode-0.1.0 → frankcode-0.1.3}/src/frankcode/setup.py

@@ -106,6 +106,20 @@ class FrankSetup:
         with open(backup_path, "w") as f:
             json.dump(main_config, f, indent=2)
 
+    async def install_skills(self):
+        import frankcode
+        import shutil
+        
+        config_dir = Path.home() / ".config" / "opencode" / "skills"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        
+        pkg_skills_dir = Path(frankcode.__file__).parent / "skills"
+        if pkg_skills_dir.exists():
+            logger.info(f"Seeding bundled skills to {config_dir}...")
+            shutil.copytree(pkg_skills_dir, config_dir, dirs_exist_ok=True)
+        else:
+            logger.debug(f"No bundled skills found in package at {pkg_skills_dir}")
+
     # We do not use preinstall_deps in CLI anymore because it lacks root permissions.
     # It is handled in agent.py now.
     async def preinstall_deps(self, instruction: str):

frankcode-0.1.3/src/frankcode/skills/archive-completed-plan/SKILL.md

@@ -0,0 +1,117 @@
+
+# Archive Completed Plan
+
+**Domain**: Plan lifecycle management, workspace hygiene
+
+**When to Use This Skill**:
+
+- After a plan has been fully executed and all tasks are complete
+- After a PR has been created for the work described in a plan
+- When the user says the plan is done or finished
+- During task completion when a `.sisyphus/plans/*.md` file was the source of work
+
+**Trigger Phrases**: "plan done", "finished plan", "archive plan", "move to completed", "plan complete"
+
+---
+
+## Philosophy
+
+**Core Principle**: Active plans live in `.sisyphus/plans/`. Completed plans move to `.sisyphus/plans/completed/`. A clean plans directory means you can glance at it and immediately see what's still in flight.
+
+---
+
+## Agent Instructions
+
+### When to Run This Protocol
+
+Execute this as the FINAL step after:
+
+1. All todo items from the plan are marked complete
+2. Build/lint/tests pass
+3. Dev servers are cleaned up (see `cleanup-dev-servers` skill)
+4. PR has been created (if applicable)
+
+### Step 1: Identify the Plan File
+
+Determine which plan file was being executed. Check:
+
+```bash
+ls .sisyphus/plans/*.md
+```
+
+If multiple active plans exist and it's ambiguous which one was just completed, ask the user:
+
+> "Which plan did we just finish? I see these active plans: [list]"
+
+### Step 2: Move to Completed
+
+```bash
+mv .sisyphus/plans/{plan-name}.md .sisyphus/plans/completed/{plan-name}.md
+```
+
+### Step 3: Verify
+
+```bash
+# Confirm the file moved
+ls .sisyphus/plans/completed/{plan-name}.md
+
+# Show remaining active plans
+ls .sisyphus/plans/*.md 2>/dev/null || echo "No active plans remaining"
+```
+
+### Step 4: Report
+
+Briefly note:
+
+- Which plan was archived
+- How many active plans remain (if any)
+
+---
+
+## Edge Cases
+
+**Plan file doesn't exist in `.sisyphus/plans/`:**
+
+- The plan may have already been moved or may live elsewhere. Don't create errors — just skip and note it.
+
+**`completed/` directory doesn't exist:**
+
+- Create it: `mkdir -p .sisyphus/plans/completed`
+
+**Plan was partially completed:**
+
+- Do NOT move it. Only archive fully completed plans. If partial, note which tasks remain.
+
+**Multiple plans completed in one session:**
+
+- Move all of them. List each one moved.
+
+---
+
+## Integration with Sisyphus Workflow
+
+This is the last step in the plan execution lifecycle:
+
+1. **Planning Phase** → Plan created in `.sisyphus/plans/`
+2. **Execution Phase** → Work done, commits made
+3. **Verification Phase** → Build, lint, tests pass
+4. **Cleanup Phase** → Dev servers killed (`cleanup-dev-servers`)
+5. **Archive Phase** → Plan moved to `completed/` (**this skill**)
+6. **Delivery Phase** → PR created, user notified
+
+---
+
+## Skill Metadata
+
+**Category**: `quick`
+
+**Required Tools**:
+
+- `bash` (for mv, ls, mkdir)
+
+**Common Combinations**:
+
+- `archive-completed-plan` + `cleanup-dev-servers` = Full post-execution cleanup
+- `archive-completed-plan` + `linear-pr-tracker` + `git-master` = Complete delivery pipeline
+
+**Estimated Time Savings**: 1 minute per plan (but prevents plan pile-up across many tasks)

frankcode-0.1.3/src/frankcode/skills/binary-re/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: binary-re
+description: Use when reverse-engineering undocumented binary files (e.g., .ckpt, .bin, .pt, .safetensors, .weights). Provides strategies for discovering binary data layouts.
+---
+
+# Binary Reverse Engineering Strategy
+
+You are working with an undocumented binary file. You must determine its data layout before writing code that reads it.
+
+## Mandatory Rules
+
+1. **DO NOT GUESS LAYOUTS FROM BYTE STATISTICS.** Do not write scripts that read random offsets and try to infer the format from floating-point distributions. This wastes enormous time and rarely converges.
+
+2. **Use the canonical library.** If the binary file is from a known framework (TensorFlow, PyTorch, HuggingFace), install the library (`pip install transformers torch` or equivalent) and use it to:
+   - Print the exact variable names, shapes, and dtypes
+   - Print the byte offsets of each tensor
+   - Run one reference forward pass and print intermediate activations
+
+3. **Hardcode the offsets.** Once you know the exact layout, hardcode the byte offsets directly into your C/implementation code. Do not write a general-purpose parser — it wastes bytes and introduces bugs.
+
+4. **Verify layer-by-layer.** After implementing each layer of a neural network, compare your intermediate activations against the reference implementation. If they diverge, fix the bug NOW before moving to the next layer. Do NOT implement all 12 layers and then try to debug from the final output.
+
+5. **Limit diagnostic scripts.** You may write at most 5 diagnostic scripts to explore the binary format. After that, you MUST have enough information to write the implementation. If you don't, you are exploring wrong — install the canonical library and use it directly.

frankcode-0.1.3/src/frankcode/skills/capture-learning/SKILL.md

@@ -0,0 +1,91 @@
+
+# Capture Learning
+
+Turn what you figured out into a reusable team playbook. Use at the end of a session, or when the Stop hook nudges you.
+
+## Step 0. Analyze the Session (Recommended)
+
+Invoke the **session-learner** agent first for a structured analysis:
+
+> "Use the session-learner agent to analyze this session for learnings."
+
+The agent identifies learnings and classifies them as SKILL, RULE, or AGENT. Use its output to guide the steps below. Skip to Step 1 if you'd rather do it manually.
+
+## Step 1. Review the Conversation
+
+Look back through the session and identify:
+- The core problem that was solved
+- The key decision or approach that worked
+- Any dead ends or gotchas encountered along the way
+
+## Step 2. Classify the Learning
+
+Not everything is a skill. Choose the right output type:
+
+| Type | When to Use | Where It Goes |
+|------|-------------|---------------|
+| **Skill** | Repeatable multi-step playbook | `hoverboard/skills/[name]/SKILL.md` |
+| **Rule** | Convention or constraint | `hoverboard/rules/[repo].md` or `CLAUDE.md` |
+| **Agent** | Specialized reviewer/analyzer role | `hoverboard/agents/[name].md` |
+
+Most learnings are **skills**. Use **rules** for "always do X" / "never do Y". Use **agents** only for reusable read-only analysis roles.
+
+## Step 3. Draft a Summary
+
+Summarize in 2-3 sentences:
+> "We were trying to [problem]. We solved it by [approach]. The key insight was [insight]."
+
+Present the summary and ask: "Does this capture it accurately? Anything to add?"
+
+## Step 4. Name It
+
+Short, hyphenated name describing the **pattern**, not the instance.
+- Good: `incremental-backfill-strategy`, `meta-rate-limit-handling`
+- Avoid: `fix-that-bug-jan-15`, `what-we-did-today`
+
+## Step 5. Create the File
+
+### For Skills
+
+Create `hoverboard/skills/[name]/SKILL.md`:
+
+```markdown
+---
+name: [skill-name]
+description: "One sentence. Triggers on: keyword1, keyword2, keyword3"
+---
+
+# [Skill Title]
+
+## Context
+What situation does this skill apply to? When should an engineer reach for it?
+
+## Approach
+Step-by-step or key decisions. Include commands, code patterns, or file paths.
+
+## Gotchas
+What went wrong or what's non-obvious? What saves time to know upfront?
+
+## References
+- Relevant PR: [link]
+- Docs: [link]
+- Related skills: [skill-name]
+```
+
+### For Rules
+
+Append to `hoverboard/rules/[repo].md` (web.md, delorean.md) or `CLAUDE.md` for cross-repo rules.
+
+### For Agents
+
+Create `hoverboard/agents/[name].md` following existing agents (code-reviewer.md, security-auditor.md).
+
+## Step 6. Remind the Engineer
+
+After creating the file:
+
+> "Learning saved at `hoverboard/[type]/[name]`. Next steps:
+> 1. Review the file and adjust if anything's off.
+> 2. Open a PR to hoverboard for team review.
+> 3. Share in **#engineering** on Slack so the team knows it exists.
+> 4. After merge, run `install.sh` in target repos to distribute."

frankcode-0.1.3/src/frankcode/skills/cartography/README.md

@@ -0,0 +1,57 @@
+# Cartography Skill
+
+Repository understanding and hierarchical codemap generation.
+
+## Overview
+
+Cartography helps orchestrators map and understand codebases by:
+
+1. Selecting relevant code/config files using LLM judgment
+2. Creating `.slim/cartography.json` for change tracking
+3. Generating empty `codemap.md` templates for explorers to fill in
+
+## Commands
+
+```bash
+# Initialize mapping
+python3 cartographer.py init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
+
+# Check what changed
+python3 cartographer.py changes --root /repo
+
+# Update hashes
+python3 cartographer.py update --root /repo
+```
+
+## Outputs
+
+### .slim/cartography.json
+
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_run": "2026-01-25T19:00:00Z",
+    "include_patterns": ["src/**/*.ts"],
+    "exclude_patterns": ["node_modules/**"]
+  },
+  "file_hashes": {
+    "src/index.ts": "abc123..."
+  },
+  "folder_hashes": {
+    "src": "def456..."
+  }
+}
+```
+
+### codemap.md (per folder)
+
+Empty templates created in each folder for explorers to fill with:
+- Responsibility
+- Design patterns
+- Data/control flow
+- Integration points
+
+## Installation
+
+Installed automatically via oh-my-opencode-slim installer when custom skills are enabled.