frankcode 0.1.1__tar.gz → 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. frankcode-0.1.3/.github/workflows/frankcode.yml +26 -0
  2. {frankcode-0.1.1 → frankcode-0.1.3}/.github/workflows/publish.yml +3 -5
  3. frankcode-0.1.3/MANIFEST.in +2 -0
  4. {frankcode-0.1.1 → frankcode-0.1.3}/PKG-INFO +1 -1
  5. {frankcode-0.1.1 → frankcode-0.1.3}/pyproject.toml +2 -0
  6. frankcode-0.1.3/src/frankcode/cli.py +163 -0
  7. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/setup.py +14 -0
  8. frankcode-0.1.3/src/frankcode/skills/archive-completed-plan/SKILL.md +117 -0
  9. frankcode-0.1.3/src/frankcode/skills/binary-re/SKILL.md +23 -0
  10. frankcode-0.1.3/src/frankcode/skills/capture-learning/SKILL.md +91 -0
  11. frankcode-0.1.3/src/frankcode/skills/cartography/README.md +57 -0
  12. frankcode-0.1.3/src/frankcode/skills/cartography/SKILL.md +137 -0
  13. frankcode-0.1.3/src/frankcode/skills/cartography/scripts/cartographer.py +456 -0
  14. frankcode-0.1.3/src/frankcode/skills/cartography/scripts/test_cartographer.py +87 -0
  15. frankcode-0.1.3/src/frankcode/skills/cleanup-dev-servers/SKILL.md +153 -0
  16. frankcode-0.1.3/src/frankcode/skills/code-golf/SKILL.md +31 -0
  17. frankcode-0.1.3/src/frankcode/skills/datadog-bug-tracer/SKILL.md +179 -0
  18. frankcode-0.1.3/src/frankcode/skills/dbt-model-pattern/SKILL.md +104 -0
  19. frankcode-0.1.3/src/frankcode/skills/defensive-execution/SKILL.md +116 -0
  20. frankcode-0.1.3/src/frankcode/skills/delorean-new-brand/SKILL.md +321 -0
  21. frankcode-0.1.3/src/frankcode/skills/delorean-patterns/SKILL.md +182 -0
  22. frankcode-0.1.3/src/frankcode/skills/delorean-pr-validation-gate/SKILL.md +102 -0
  23. frankcode-0.1.3/src/frankcode/skills/design-consistency/SKILL.md +535 -0
  24. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/bug-bash-patterns.md +565 -0
  25. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/card-patterns.md +44 -0
  26. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/component-patterns.md +24 -0
  27. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/component-registry.md +937 -0
  28. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/design-tokens.md +30 -0
  29. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/experience-principles.md +213 -0
  30. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/figma-tokens.md +290 -0
  31. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/imports.md +33 -0
  32. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/patterns.md +2013 -0
  33. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/pr-checklist.md +299 -0
  34. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/prototyping-patterns.md +200 -0
  35. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/skeleton-patterns.md +57 -0
  36. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/state-management.md +14 -0
  37. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/toggle-group-patterns.md +56 -0
  38. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/typography.md +25 -0
  39. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/ui-dos-and-donts.md +92 -0
  40. frankcode-0.1.3/src/frankcode/skills/design-consistency/references/variant-props.md +895 -0
  41. frankcode-0.1.3/src/frankcode/skills/e2e-test-pattern/SKILL.md +97 -0
  42. frankcode-0.1.3/src/frankcode/skills/forge-agent/SKILL.md +86 -0
  43. frankcode-0.1.3/src/frankcode/skills/frontend-design/LICENSE.txt +177 -0
  44. frankcode-0.1.3/src/frankcode/skills/frontend-design/SKILL.md +37 -0
  45. frankcode-0.1.3/src/frankcode/skills/git-worktree-master/SKILL.md +423 -0
  46. frankcode-0.1.3/src/frankcode/skills/iac-new-brand/SKILL.md +264 -0
  47. frankcode-0.1.3/src/frankcode/skills/linear-pr-tracker/SKILL.md +403 -0
  48. frankcode-0.1.3/src/frankcode/skills/modernize-first/SKILL.md +84 -0
  49. frankcode-0.1.3/src/frankcode/skills/modernize-first/references/migration-patterns.md +424 -0
  50. frankcode-0.1.3/src/frankcode/skills/new-api-endpoint/SKILL.md +67 -0
  51. frankcode-0.1.3/src/frankcode/skills/pr-review/SKILL.md +40 -0
  52. frankcode-0.1.3/src/frankcode/skills/pr-validation-gate/SKILL.md +126 -0
  53. frankcode-0.1.3/src/frankcode/skills/senior-fe-planning/SKILL.md +169 -0
  54. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/SKILL.md +288 -0
  55. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/chart.md +306 -0
  56. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/learn.md +145 -0
  57. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/official-ui-reference.md +1729 -0
  58. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/reference.md +586 -0
  59. frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/ui-reference.md +1578 -0
  60. frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/SKILL.md +242 -0
  61. frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/code-quality-reviewer-prompt.md +20 -0
  62. frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/implementer-prompt.md +78 -0
  63. frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  64. frankcode-0.1.3/src/frankcode/skills/superpowers/brainstorming/SKILL.md +54 -0
  65. frankcode-0.1.3/src/frankcode/skills/superpowers/dispatching-parallel-agents/SKILL.md +180 -0
  66. frankcode-0.1.3/src/frankcode/skills/superpowers/executing-plans/SKILL.md +84 -0
  67. frankcode-0.1.3/src/frankcode/skills/superpowers/finishing-a-development-branch/SKILL.md +200 -0
  68. frankcode-0.1.3/src/frankcode/skills/superpowers/receiving-code-review/SKILL.md +213 -0
  69. frankcode-0.1.3/src/frankcode/skills/superpowers/requesting-code-review/SKILL.md +105 -0
  70. frankcode-0.1.3/src/frankcode/skills/superpowers/requesting-code-review/code-reviewer.md +146 -0
  71. frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/SKILL.md +242 -0
  72. frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/code-quality-reviewer-prompt.md +20 -0
  73. frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/implementer-prompt.md +78 -0
  74. frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  75. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/CREATION-LOG.md +119 -0
  76. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/SKILL.md +296 -0
  77. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/condition-based-waiting-example.ts +158 -0
  78. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/condition-based-waiting.md +115 -0
  79. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/defense-in-depth.md +122 -0
  80. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/find-polluter.sh +63 -0
  81. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/root-cause-tracing.md +169 -0
  82. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-academic.md +14 -0
  83. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-1.md +58 -0
  84. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-2.md +68 -0
  85. frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-3.md +69 -0
  86. frankcode-0.1.3/src/frankcode/skills/superpowers/test-driven-development/SKILL.md +379 -0
  87. frankcode-0.1.3/src/frankcode/skills/superpowers/test-driven-development/testing-anti-patterns.md +299 -0
  88. frankcode-0.1.3/src/frankcode/skills/superpowers/using-git-worktrees/SKILL.md +218 -0
  89. frankcode-0.1.3/src/frankcode/skills/superpowers/using-superpowers/SKILL.md +87 -0
  90. frankcode-0.1.3/src/frankcode/skills/superpowers/verification-before-completion/SKILL.md +139 -0
  91. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-plans/SKILL.md +116 -0
  92. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/SKILL.md +655 -0
  93. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/anthropic-best-practices.md +1150 -0
  94. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/examples/CLAUDE_MD_TESTING.md +189 -0
  95. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/graphviz-conventions.dot +172 -0
  96. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/persuasion-principles.md +187 -0
  97. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/render-graphs.js +168 -0
  98. frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/testing-skills-with-subagents.md +384 -0
  99. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/SKILL.md +105 -0
  100. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/api-routes.md +238 -0
  101. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/auth-route-protection.md +192 -0
  102. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/auth-session-management.md +191 -0
  103. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/deploy-adapters.md +201 -0
  104. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/env-functions.md +211 -0
  105. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/err-server-errors.md +187 -0
  106. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/file-separation.md +152 -0
  107. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/mw-request-middleware.md +166 -0
  108. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/sf-create-server-fn.md +146 -0
  109. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/sf-input-validation.md +158 -0
  110. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-hydration-safety.md +187 -0
  111. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-prerender.md +199 -0
  112. frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-streaming.md +201 -0
  113. frankcode-0.1.3/src/frankcode/skills/test-api-endpoint/SKILL.md +71 -0
  114. frankcode-0.1.3/src/frankcode/skills/test-api-endpoint/evals/evals.json +119 -0
  115. frankcode-0.1.3/src/frankcode/skills/upload-creative-templates/SKILL.md +144 -0
  116. frankcode-0.1.3/src/frankcode/skills/web-patterns/SKILL.md +321 -0
  117. frankcode-0.1.3/src/frankcode/skills/web-pr-validation-gate/SKILL.md +127 -0
  118. frankcode-0.1.3/src/frankcode/skills/worktree-enforcer/SKILL.md +250 -0
  119. frankcode-0.1.3/src/frankcode/skills/worktrunk-setup/SKILL.md +387 -0
  120. frankcode-0.1.3/src/frankcode/skills/write-skill/SKILL.md +225 -0
  121. frankcode-0.1.3/src/frankcode/skills/write-skill/references/description-examples.md +102 -0
  122. frankcode-0.1.3/src/frankcode/skills/write-skill/references/skill-template.md +86 -0
  123. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/PKG-INFO +1 -1
  124. frankcode-0.1.3/src/frankcode.egg-info/SOURCES.txt +143 -0
  125. frankcode-0.1.3/tests/unit/test_setup.py +34 -0
  126. frankcode-0.1.1/src/frankcode/cli.py +0 -69
  127. frankcode-0.1.1/src/frankcode.egg-info/SOURCES.txt +0 -26
  128. frankcode-0.1.1/tests/unit/test_setup.py +0 -27
  129. {frankcode-0.1.1 → frankcode-0.1.3}/.github/workflows/test.yml +0 -0
  130. {frankcode-0.1.1 → frankcode-0.1.3}/.gitignore +0 -0
  131. {frankcode-0.1.1 → frankcode-0.1.3}/LICENSE +0 -0
  132. {frankcode-0.1.1 → frankcode-0.1.3}/README.md +0 -0
  133. {frankcode-0.1.1 → frankcode-0.1.3}/setup.cfg +0 -0
  134. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/__init__.py +0 -0
  135. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/oh-my-opencode-slim.json +0 -0
  136. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/opencode-verify.json +0 -0
  137. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/opencode.json +0 -0
  138. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/prompt-rules.json +0 -0
  139. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/environment.py +0 -0
  140. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/orchestrator.py +0 -0
  141. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/utils.py +0 -0
  142. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/dependency_links.txt +0 -0
  143. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/entry_points.txt +0 -0
  144. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/requires.txt +0 -0
  145. {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/top_level.txt +0 -0
  146. {frankcode-0.1.1 → frankcode-0.1.3}/tests/conftest.py +0 -0
  147. {frankcode-0.1.1 → frankcode-0.1.3}/tests/unit/test_environment.py +0 -0
  148. {frankcode-0.1.1 → frankcode-0.1.3}/tests/unit/test_watchdog.py +0 -0
@@ -0,0 +1,26 @@
1
+ name: FrankCode Issue Responder
2
+
3
+ on:
4
+ issue_comment:
5
+ types: [created]
6
+
7
+ permissions:
8
+ contents: write
9
+ pull-requests: write
10
+ issues: write
11
+
12
+ jobs:
13
+ frankcode-run:
14
+ # Only run on issue comments (not PRs) that contain '@frankcode'
15
+ if: ${{ !github.event.issue.pull_request && contains(github.event.comment.body, '@frankcode') }}
16
+ runs-on: ubuntu-latest
17
+
18
+ steps:
19
+ - name: Checkout repository
20
+ uses: actions/checkout@v4
21
+
22
+ - name: Run FrankCode Action
23
+ uses: joeyism/frankcode-action@main
24
+ with:
25
+ api-key: ${{ secrets.GEMINI_API_KEY }}
26
+ github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -3,7 +3,7 @@ name: Publish to PyPI and GitHub Releases
3
3
  on:
4
4
  push:
5
5
  tags:
6
- - 'v*' # Triggers when a new tag like v0.1.0 is pushed
6
+ - 'v*'
7
7
 
8
8
  jobs:
9
9
  build-and-publish:
@@ -17,14 +17,14 @@ jobs:
17
17
  steps:
18
18
  - uses: actions/checkout@v4
19
19
  with:
20
- fetch-depth: 0 # Needed for setuptools_scm to resolve version correctly
20
+ fetch-depth: 0
21
21
 
22
22
  - name: Set up Python
23
23
  uses: actions/setup-python@v5
24
24
  with:
25
25
  python-version: "3.12"
26
26
 
27
- - name: Install build tool
27
+ - name: Install build tools
28
28
  run: python -m pip install --upgrade pip build
29
29
 
30
30
  - name: Build package
@@ -38,5 +38,3 @@ jobs:
38
38
 
39
39
  - name: Publish package distributions to PyPI
40
40
  uses: pypa/gh-action-pypi-publish@release/v1
41
- # Note: PyPI publish will fail if you haven't set up Trusted Publishing on PyPI yet.
42
- # If it fails, the GitHub Release will still be created!
@@ -0,0 +1,2 @@
1
+ recursive-include src/frankcode/configs *
2
+ recursive-include src/frankcode/skills *
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: frankcode
3
- Version: 0.1.1
3
+ Version: 0.1.3
4
4
  Summary: Advanced multi-agent orchestrator for OpenCode
5
5
  Author: joeyism
6
6
  License: MIT
@@ -37,6 +37,8 @@ build-backend = "setuptools.build_meta"
37
37
 
38
38
  [tool.setuptools_scm]
39
39
 
40
+ [tool.setuptools]
41
+ include-package-data = true
40
42
 
41
43
  [tool.setuptools.package-data]
42
44
  frankcode = ["configs/*.json"]
@@ -0,0 +1,163 @@
1
+ import typer
2
+ import asyncio
3
+ import logging
4
+ from typing import Optional
5
+ from rich.console import Console
6
+ from rich.logging import RichHandler
7
+
8
+ from .environment import LocalEnvironment
9
+ from .setup import FrankSetup
10
+ from .orchestrator import FrankOrchestrator, resolve_nvm_path
11
+
12
+ app = typer.Typer()
13
+ console = Console()
14
+
15
+ def setup_logging(verbose: bool):
16
+ level = logging.DEBUG if verbose else logging.INFO
17
+ logging.basicConfig(
18
+ level=level,
19
+ format="%(message)s",
20
+ datefmt="[%X]",
21
+ handlers=[RichHandler(rich_tracebacks=True)]
22
+ )
23
+
24
+ @app.command()
25
+ def main(
26
+ prompt: str,
27
+ model: str = typer.Option("google/gemini-3.1-pro-preview", help="LLM model to use"),
28
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Show debug logs"),
29
+ verify: bool = typer.Option(True, help="Enable verification and fix passes"),
30
+ clean: bool = typer.Option(False, help="Wipe .frankcode directory before starting"),
31
+ harbor_mode: bool = typer.Option(False, help="Exit with code 0 even if verification fails (for harbor compatibility)")
32
+ ):
33
+ setup_logging(verbose)
34
+
35
+ if clean:
36
+ import shutil
37
+ import os
38
+ if os.path.exists(".frankcode"):
39
+ shutil.rmtree(".frankcode")
40
+
41
+ env = LocalEnvironment()
42
+ setup = FrankSetup(env, ".")
43
+ orchestrator = FrankOrchestrator(env, setup, model)
44
+
45
+ async def run():
46
+ # Step 0: Resolve NVM paths so npm/opencode are available
47
+ await resolve_nvm_path(env)
48
+
49
+ # Step 1: Install plugins and write configs
50
+ console.print("[bold blue]Installing safety plugins and generating configs...[/bold blue]")
51
+ await setup.ensure_directories()
52
+ await setup.install_plugins()
53
+ await setup.inject_plugins_into_system_configs()
54
+
55
+ # Step 1.5: Seed bundled skills
56
+ await setup.install_skills()
57
+
58
+ # Step 3: Run the task
59
+ console.print(f"[bold green]Executing task:[/bold green] {prompt}")
60
+ success = await orchestrator.run_task(prompt, verify=verify)
61
+
62
+ if success:
63
+ console.print("[bold green]Task completed successfully![/bold green]")
64
+ else:
65
+ console.print("[bold red]Task failed to verify.[/bold red]")
66
+ if not harbor_mode:
67
+ raise typer.Exit(code=1)
68
+
69
+ asyncio.run(run())
70
+
71
+ @app.command()
72
+ def init_github():
73
+ """
74
+ Scaffold a GitHub Actions workflow file to run FrankCode on issue comments.
75
+ """
76
+ import os
77
+ workflow_dir = ".github/workflows"
78
+ os.makedirs(workflow_dir, exist_ok=True)
79
+
80
+ workflow_path = os.path.join(workflow_dir, "frankcode.yml")
81
+
82
+ workflow_content = """name: FrankCode Issue Responder
83
+
84
+ on:
85
+ issue_comment:
86
+ types: [created]
87
+
88
+ permissions:
89
+ contents: write
90
+ pull-requests: write
91
+ issues: write
92
+
93
+ jobs:
94
+ frankcode-run:
95
+ if: ${{ !github.event.issue.pull_request && contains(github.event.comment.body, '@frankcode') }}
96
+ runs-on: ubuntu-latest
97
+
98
+ steps:
99
+ - name: Checkout repository
100
+ uses: actions/checkout@v4
101
+
102
+ - name: Setup Node.js (for OpenCode)
103
+ uses: actions/setup-node@v4
104
+ with:
105
+ node-version: '20'
106
+
107
+ - name: Setup Python (for FrankCode)
108
+ uses: actions/setup-python@v5
109
+ with:
110
+ python-version: '3.11'
111
+
112
+ - name: Install Dependencies
113
+ run: |
114
+ npm install -g opencode
115
+ pip install git+https://github.com/joeyism/frankcode-py.git
116
+
117
+ - name: Prepare Prompt
118
+ id: prompt
119
+ run: |
120
+ cat << 'EOF' > frankcode_prompt.txt
121
+ Please resolve the following issue.
122
+
123
+ Title: ${{ github.event.issue.title }}
124
+
125
+ Issue Description:
126
+ ${{ github.event.issue.body }}
127
+
128
+ Instruction from comment:
129
+ ${{ github.event.comment.body }}
130
+ EOF
131
+
132
+ - name: Run FrankCode
133
+ env:
134
+ GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
135
+ run: |
136
+ frankcode "$(cat frankcode_prompt.txt)"
137
+
138
+ - name: Create Pull Request
139
+ uses: peter-evans/create-pull-request@v6
140
+ with:
141
+ token: ${{ secrets.GITHUB_TOKEN }}
142
+ commit-message: "FrankCode: Implement fix for issue #${{ github.event.issue.number }}"
143
+ title: "FrankCode: Fix issue #${{ github.event.issue.number }} - ${{ github.event.issue.title }}"
144
+ body: |
145
+ This PR was generated by FrankCode in response to [Issue #${{ github.event.issue.number }}](${{ github.event.issue.html_url }}).
146
+
147
+ Triggered by comment:
148
+ > ${{ github.event.comment.body }}
149
+ branch: "frankcode/issue-${{ github.event.issue.number }}"
150
+ base: ${{ github.event.repository.default_branch }}
151
+ labels: "frankcode, automated pr"
152
+ assignees: ${{ github.actor }}
153
+ """
154
+ if os.path.exists(workflow_path):
155
+ console.print(f"[yellow]Warning: {workflow_path} already exists. Skipping.[/yellow]")
156
+ else:
157
+ with open(workflow_path, "w") as f:
158
+ f.write(workflow_content)
159
+ console.print(f"[bold green]Successfully created {workflow_path}[/bold green]")
160
+ console.print("Make sure to add your [bold cyan]GEMINI_API_KEY[/bold cyan] to your repository's GitHub Actions secrets!")
161
+
162
+ if __name__ == "__main__":
163
+ app()
@@ -106,6 +106,20 @@ class FrankSetup:
106
106
  with open(backup_path, "w") as f:
107
107
  json.dump(main_config, f, indent=2)
108
108
 
109
+ async def install_skills(self):
110
+ import frankcode
111
+ import shutil
112
+
113
+ config_dir = Path.home() / ".config" / "opencode" / "skills"
114
+ config_dir.mkdir(parents=True, exist_ok=True)
115
+
116
+ pkg_skills_dir = Path(frankcode.__file__).parent / "skills"
117
+ if pkg_skills_dir.exists():
118
+ logger.info(f"Seeding bundled skills to {config_dir}...")
119
+ shutil.copytree(pkg_skills_dir, config_dir, dirs_exist_ok=True)
120
+ else:
121
+ logger.debug(f"No bundled skills found in package at {pkg_skills_dir}")
122
+
109
123
  # We do not use preinstall_deps in CLI anymore because it lacks root permissions.
110
124
  # It is handled in agent.py now.
111
125
  async def preinstall_deps(self, instruction: str):
@@ -0,0 +1,117 @@
1
+
2
+ # Archive Completed Plan
3
+
4
+ **Domain**: Plan lifecycle management, workspace hygiene
5
+
6
+ **When to Use This Skill**:
7
+
8
+ - After a plan has been fully executed and all tasks are complete
9
+ - After a PR has been created for the work described in a plan
10
+ - When the user says the plan is done or finished
11
+ - During task completion when a `.sisyphus/plans/*.md` file was the source of work
12
+
13
+ **Trigger Phrases**: "plan done", "finished plan", "archive plan", "move to completed", "plan complete"
14
+
15
+ ---
16
+
17
+ ## Philosophy
18
+
19
+ **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.
20
+
21
+ ---
22
+
23
+ ## Agent Instructions
24
+
25
+ ### When to Run This Protocol
26
+
27
+ Execute this as the FINAL step after:
28
+
29
+ 1. All todo items from the plan are marked complete
30
+ 2. Build/lint/tests pass
31
+ 3. Dev servers are cleaned up (see `cleanup-dev-servers` skill)
32
+ 4. PR has been created (if applicable)
33
+
34
+ ### Step 1: Identify the Plan File
35
+
36
+ Determine which plan file was being executed. Check:
37
+
38
+ ```bash
39
+ ls .sisyphus/plans/*.md
40
+ ```
41
+
42
+ If multiple active plans exist and it's ambiguous which one was just completed, ask the user:
43
+
44
+ > "Which plan did we just finish? I see these active plans: [list]"
45
+
46
+ ### Step 2: Move to Completed
47
+
48
+ ```bash
49
+ mv .sisyphus/plans/{plan-name}.md .sisyphus/plans/completed/{plan-name}.md
50
+ ```
51
+
52
+ ### Step 3: Verify
53
+
54
+ ```bash
55
+ # Confirm the file moved
56
+ ls .sisyphus/plans/completed/{plan-name}.md
57
+
58
+ # Show remaining active plans
59
+ ls .sisyphus/plans/*.md 2>/dev/null || echo "No active plans remaining"
60
+ ```
61
+
62
+ ### Step 4: Report
63
+
64
+ Briefly note:
65
+
66
+ - Which plan was archived
67
+ - How many active plans remain (if any)
68
+
69
+ ---
70
+
71
+ ## Edge Cases
72
+
73
+ **Plan file doesn't exist in `.sisyphus/plans/`:**
74
+
75
+ - The plan may have already been moved or may live elsewhere. Don't create errors — just skip and note it.
76
+
77
+ **`completed/` directory doesn't exist:**
78
+
79
+ - Create it: `mkdir -p .sisyphus/plans/completed`
80
+
81
+ **Plan was partially completed:**
82
+
83
+ - Do NOT move it. Only archive fully completed plans. If partial, note which tasks remain.
84
+
85
+ **Multiple plans completed in one session:**
86
+
87
+ - Move all of them. List each one moved.
88
+
89
+ ---
90
+
91
+ ## Integration with Sisyphus Workflow
92
+
93
+ This is the last step in the plan execution lifecycle:
94
+
95
+ 1. **Planning Phase** → Plan created in `.sisyphus/plans/`
96
+ 2. **Execution Phase** → Work done, commits made
97
+ 3. **Verification Phase** → Build, lint, tests pass
98
+ 4. **Cleanup Phase** → Dev servers killed (`cleanup-dev-servers`)
99
+ 5. **Archive Phase** → Plan moved to `completed/` (**this skill**)
100
+ 6. **Delivery Phase** → PR created, user notified
101
+
102
+ ---
103
+
104
+ ## Skill Metadata
105
+
106
+ **Category**: `quick`
107
+
108
+ **Required Tools**:
109
+
110
+ - `bash` (for mv, ls, mkdir)
111
+
112
+ **Common Combinations**:
113
+
114
+ - `archive-completed-plan` + `cleanup-dev-servers` = Full post-execution cleanup
115
+ - `archive-completed-plan` + `linear-pr-tracker` + `git-master` = Complete delivery pipeline
116
+
117
+ **Estimated Time Savings**: 1 minute per plan (but prevents plan pile-up across many tasks)
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: binary-re
3
+ description: Use when reverse-engineering undocumented binary files (e.g., .ckpt, .bin, .pt, .safetensors, .weights). Provides strategies for discovering binary data layouts.
4
+ ---
5
+
6
+ # Binary Reverse Engineering Strategy
7
+
8
+ You are working with an undocumented binary file. You must determine its data layout before writing code that reads it.
9
+
10
+ ## Mandatory Rules
11
+
12
+ 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.
13
+
14
+ 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:
15
+ - Print the exact variable names, shapes, and dtypes
16
+ - Print the byte offsets of each tensor
17
+ - Run one reference forward pass and print intermediate activations
18
+
19
+ 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.
20
+
21
+ 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.
22
+
23
+ 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.
@@ -0,0 +1,91 @@
1
+
2
+ # Capture Learning
3
+
4
+ Turn what you figured out into a reusable team playbook. Use at the end of a session, or when the Stop hook nudges you.
5
+
6
+ ## Step 0. Analyze the Session (Recommended)
7
+
8
+ Invoke the **session-learner** agent first for a structured analysis:
9
+
10
+ > "Use the session-learner agent to analyze this session for learnings."
11
+
12
+ 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.
13
+
14
+ ## Step 1. Review the Conversation
15
+
16
+ Look back through the session and identify:
17
+ - The core problem that was solved
18
+ - The key decision or approach that worked
19
+ - Any dead ends or gotchas encountered along the way
20
+
21
+ ## Step 2. Classify the Learning
22
+
23
+ Not everything is a skill. Choose the right output type:
24
+
25
+ | Type | When to Use | Where It Goes |
26
+ |------|-------------|---------------|
27
+ | **Skill** | Repeatable multi-step playbook | `hoverboard/skills/[name]/SKILL.md` |
28
+ | **Rule** | Convention or constraint | `hoverboard/rules/[repo].md` or `CLAUDE.md` |
29
+ | **Agent** | Specialized reviewer/analyzer role | `hoverboard/agents/[name].md` |
30
+
31
+ Most learnings are **skills**. Use **rules** for "always do X" / "never do Y". Use **agents** only for reusable read-only analysis roles.
32
+
33
+ ## Step 3. Draft a Summary
34
+
35
+ Summarize in 2-3 sentences:
36
+ > "We were trying to [problem]. We solved it by [approach]. The key insight was [insight]."
37
+
38
+ Present the summary and ask: "Does this capture it accurately? Anything to add?"
39
+
40
+ ## Step 4. Name It
41
+
42
+ Short, hyphenated name describing the **pattern**, not the instance.
43
+ - Good: `incremental-backfill-strategy`, `meta-rate-limit-handling`
44
+ - Avoid: `fix-that-bug-jan-15`, `what-we-did-today`
45
+
46
+ ## Step 5. Create the File
47
+
48
+ ### For Skills
49
+
50
+ Create `hoverboard/skills/[name]/SKILL.md`:
51
+
52
+ ```markdown
53
+ ---
54
+ name: [skill-name]
55
+ description: "One sentence. Triggers on: keyword1, keyword2, keyword3"
56
+ ---
57
+
58
+ # [Skill Title]
59
+
60
+ ## Context
61
+ What situation does this skill apply to? When should an engineer reach for it?
62
+
63
+ ## Approach
64
+ Step-by-step or key decisions. Include commands, code patterns, or file paths.
65
+
66
+ ## Gotchas
67
+ What went wrong or what's non-obvious? What saves time to know upfront?
68
+
69
+ ## References
70
+ - Relevant PR: [link]
71
+ - Docs: [link]
72
+ - Related skills: [skill-name]
73
+ ```
74
+
75
+ ### For Rules
76
+
77
+ Append to `hoverboard/rules/[repo].md` (web.md, delorean.md) or `CLAUDE.md` for cross-repo rules.
78
+
79
+ ### For Agents
80
+
81
+ Create `hoverboard/agents/[name].md` following existing agents (code-reviewer.md, security-auditor.md).
82
+
83
+ ## Step 6. Remind the Engineer
84
+
85
+ After creating the file:
86
+
87
+ > "Learning saved at `hoverboard/[type]/[name]`. Next steps:
88
+ > 1. Review the file and adjust if anything's off.
89
+ > 2. Open a PR to hoverboard for team review.
90
+ > 3. Share in **#engineering** on Slack so the team knows it exists.
91
+ > 4. After merge, run `install.sh` in target repos to distribute."
@@ -0,0 +1,57 @@
1
+ # Cartography Skill
2
+
3
+ Repository understanding and hierarchical codemap generation.
4
+
5
+ ## Overview
6
+
7
+ Cartography helps orchestrators map and understand codebases by:
8
+
9
+ 1. Selecting relevant code/config files using LLM judgment
10
+ 2. Creating `.slim/cartography.json` for change tracking
11
+ 3. Generating empty `codemap.md` templates for explorers to fill in
12
+
13
+ ## Commands
14
+
15
+ ```bash
16
+ # Initialize mapping
17
+ python3 cartographer.py init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
18
+
19
+ # Check what changed
20
+ python3 cartographer.py changes --root /repo
21
+
22
+ # Update hashes
23
+ python3 cartographer.py update --root /repo
24
+ ```
25
+
26
+ ## Outputs
27
+
28
+ ### .slim/cartography.json
29
+
30
+ ```json
31
+ {
32
+ "metadata": {
33
+ "version": "1.0.0",
34
+ "last_run": "2026-01-25T19:00:00Z",
35
+ "include_patterns": ["src/**/*.ts"],
36
+ "exclude_patterns": ["node_modules/**"]
37
+ },
38
+ "file_hashes": {
39
+ "src/index.ts": "abc123..."
40
+ },
41
+ "folder_hashes": {
42
+ "src": "def456..."
43
+ }
44
+ }
45
+ ```
46
+
47
+ ### codemap.md (per folder)
48
+
49
+ Empty templates created in each folder for explorers to fill with:
50
+ - Responsibility
51
+ - Design patterns
52
+ - Data/control flow
53
+ - Integration points
54
+
55
+ ## Installation
56
+
57
+ Installed automatically via oh-my-opencode-slim installer when custom skills are enabled.
@@ -0,0 +1,137 @@
1
+ ---
2
+ name: cartography
3
+ description: Repository understanding and hierarchical codemap generation
4
+ ---
5
+
6
+ # Cartography Skill
7
+
8
+ You help users understand and map repositories by creating hierarchical codemaps.
9
+
10
+ ## When to Use
11
+
12
+ - User asks to understand/map a repository
13
+ - User wants codebase documentation
14
+ - Starting work on an unfamiliar codebase
15
+
16
+ ## Workflow
17
+
18
+ ### Step 1: Check for Existing State
19
+
20
+ **First, check if `.slim/cartography.json` exists in the repo root.**
21
+
22
+ If it **exists**: Skip to Step 3 (Detect Changes) - no need to re-initialize.
23
+
24
+ If it **doesn't exist**: Continue to Step 2 (Initialize).
25
+
26
+ ### Step 2: Initialize (Only if no state exists)
27
+
28
+ 1. **Analyze the repository structure** - List files, understand directories
29
+ 2. **Infer patterns** for **core code/config files ONLY** to include:
30
+ - **Include**: `src/**/*.ts`, `package.json`, etc.
31
+ - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
32
+ - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
33
+ - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
34
+ - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
35
+ - Respect `.gitignore` automatically
36
+ 3. **Run cartographer.py init**:
37
+
38
+ ```bash
39
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
40
+ --root ./ \
41
+ --include "src/**/*.ts" \
42
+ --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
43
+ ```
44
+
45
+ This creates:
46
+ - `.slim/cartography.json` - File and folder hashes for change detection
47
+ - Empty `codemap.md` files in all relevant subdirectories
48
+
49
+ 4. **Delegate to Explorer agents** - Spawn one explorer per folder to read code and fill in its specific `codemap.md` file.
50
+
51
+ ### Step 3: Detect Changes (If state already exists)
52
+
53
+ 1. **Run cartographer.py changes** to see what changed:
54
+
55
+ ```bash
56
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
57
+ --root ./
58
+ ```
59
+
60
+ 2. **Review the output** - It shows:
61
+ - Added files
62
+ - Removed files
63
+ - Modified files
64
+ - Affected folders
65
+
66
+ 3. **Only update affected codemaps** - Spawn one explorer per affected folder to update its `codemap.md`.
67
+ 4. **Run update** to save new state:
68
+
69
+ ```bash
70
+ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
71
+ --root ./
72
+ ```
73
+
74
+ ### Step 4: Finalize Repository Atlas (Root Codemap)
75
+
76
+ Once all specific directories are mapped, the Orchestrator must create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.
77
+
78
+ 1. **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
79
+ 2. **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map.
80
+ 3. **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.
81
+
82
+
83
+ ## Codemap Content
84
+
85
+ Explorers are granted write permissions for `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
86
+
87
+ - **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
88
+ - **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
89
+ - **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
90
+ - **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
91
+
92
+ Example codemap:
93
+
94
+ ```markdown
95
+ # src/agents/
96
+
97
+ ## Responsibility
98
+ Defines agent personalities and manages their configuration lifecycle.
99
+
100
+ ## Design
101
+ Each agent is a prompt + permission set. Config system uses:
102
+ - Default prompts (orchestrator.ts, explorer.ts, etc.)
103
+ - User overrides from ~/.config/opencode/oh-my-opencode-slim.json
104
+ - Permission wildcards for skill/MCP access control
105
+
106
+ ## Flow
107
+ 1. Plugin loads → calls getAgentConfigs()
108
+ 2. Reads user config preset
109
+ 3. Merges defaults with overrides
110
+ 4. Applies permission rules (wildcard expansion)
111
+ 5. Returns agent configs to OpenCode
112
+
113
+ ## Integration
114
+ - Consumed by: Main plugin (src/index.ts)
115
+ - Depends on: Config loader, skills registry
116
+ ```
117
+
118
+ Example **Root Codemap (Atlas)**:
119
+
120
+ ```markdown
121
+ # Repository Atlas: oh-my-opencode-slim
122
+
123
+ ## Project Responsibility
124
+ A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.
125
+
126
+ ## System Entry Points
127
+ - `src/index.ts`: Plugin initialization and OpenCode integration.
128
+ - `package.json`: Dependency manifest and build scripts.
129
+ - `oh-my-opencode-slim.json`: User configuration schema.
130
+
131
+ ## Directory Map (Aggregated)
132
+ | Directory | Responsibility Summary | Detailed Map |
133
+ |-----------|------------------------|--------------|
134
+ | `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
135
+ | `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
136
+ | `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
137
+ ```