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.
- frankcode-0.1.3/.github/workflows/frankcode.yml +26 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/.github/workflows/publish.yml +3 -5
- frankcode-0.1.3/MANIFEST.in +2 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/PKG-INFO +1 -1
- {frankcode-0.1.1 → frankcode-0.1.3}/pyproject.toml +2 -0
- frankcode-0.1.3/src/frankcode/cli.py +163 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/setup.py +14 -0
- frankcode-0.1.3/src/frankcode/skills/archive-completed-plan/SKILL.md +117 -0
- frankcode-0.1.3/src/frankcode/skills/binary-re/SKILL.md +23 -0
- frankcode-0.1.3/src/frankcode/skills/capture-learning/SKILL.md +91 -0
- frankcode-0.1.3/src/frankcode/skills/cartography/README.md +57 -0
- frankcode-0.1.3/src/frankcode/skills/cartography/SKILL.md +137 -0
- frankcode-0.1.3/src/frankcode/skills/cartography/scripts/cartographer.py +456 -0
- frankcode-0.1.3/src/frankcode/skills/cartography/scripts/test_cartographer.py +87 -0
- frankcode-0.1.3/src/frankcode/skills/cleanup-dev-servers/SKILL.md +153 -0
- frankcode-0.1.3/src/frankcode/skills/code-golf/SKILL.md +31 -0
- frankcode-0.1.3/src/frankcode/skills/datadog-bug-tracer/SKILL.md +179 -0
- frankcode-0.1.3/src/frankcode/skills/dbt-model-pattern/SKILL.md +104 -0
- frankcode-0.1.3/src/frankcode/skills/defensive-execution/SKILL.md +116 -0
- frankcode-0.1.3/src/frankcode/skills/delorean-new-brand/SKILL.md +321 -0
- frankcode-0.1.3/src/frankcode/skills/delorean-patterns/SKILL.md +182 -0
- frankcode-0.1.3/src/frankcode/skills/delorean-pr-validation-gate/SKILL.md +102 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/SKILL.md +535 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/bug-bash-patterns.md +565 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/card-patterns.md +44 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/component-patterns.md +24 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/component-registry.md +937 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/design-tokens.md +30 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/experience-principles.md +213 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/figma-tokens.md +290 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/imports.md +33 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/patterns.md +2013 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/pr-checklist.md +299 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/prototyping-patterns.md +200 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/skeleton-patterns.md +57 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/state-management.md +14 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/toggle-group-patterns.md +56 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/typography.md +25 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/ui-dos-and-donts.md +92 -0
- frankcode-0.1.3/src/frankcode/skills/design-consistency/references/variant-props.md +895 -0
- frankcode-0.1.3/src/frankcode/skills/e2e-test-pattern/SKILL.md +97 -0
- frankcode-0.1.3/src/frankcode/skills/forge-agent/SKILL.md +86 -0
- frankcode-0.1.3/src/frankcode/skills/frontend-design/LICENSE.txt +177 -0
- frankcode-0.1.3/src/frankcode/skills/frontend-design/SKILL.md +37 -0
- frankcode-0.1.3/src/frankcode/skills/git-worktree-master/SKILL.md +423 -0
- frankcode-0.1.3/src/frankcode/skills/iac-new-brand/SKILL.md +264 -0
- frankcode-0.1.3/src/frankcode/skills/linear-pr-tracker/SKILL.md +403 -0
- frankcode-0.1.3/src/frankcode/skills/modernize-first/SKILL.md +84 -0
- frankcode-0.1.3/src/frankcode/skills/modernize-first/references/migration-patterns.md +424 -0
- frankcode-0.1.3/src/frankcode/skills/new-api-endpoint/SKILL.md +67 -0
- frankcode-0.1.3/src/frankcode/skills/pr-review/SKILL.md +40 -0
- frankcode-0.1.3/src/frankcode/skills/pr-validation-gate/SKILL.md +126 -0
- frankcode-0.1.3/src/frankcode/skills/senior-fe-planning/SKILL.md +169 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/SKILL.md +288 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/chart.md +306 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/learn.md +145 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/official-ui-reference.md +1729 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/reference.md +586 -0
- frankcode-0.1.3/src/frankcode/skills/shadcn-ui/references/ui-reference.md +1578 -0
- frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/SKILL.md +242 -0
- frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/code-quality-reviewer-prompt.md +20 -0
- frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/implementer-prompt.md +78 -0
- frankcode-0.1.3/src/frankcode/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/brainstorming/SKILL.md +54 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/dispatching-parallel-agents/SKILL.md +180 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/executing-plans/SKILL.md +84 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/finishing-a-development-branch/SKILL.md +200 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/receiving-code-review/SKILL.md +213 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/requesting-code-review/SKILL.md +105 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/requesting-code-review/code-reviewer.md +146 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/SKILL.md +242 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/code-quality-reviewer-prompt.md +20 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/implementer-prompt.md +78 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/CREATION-LOG.md +119 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/SKILL.md +296 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/condition-based-waiting-example.ts +158 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/condition-based-waiting.md +115 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/defense-in-depth.md +122 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/find-polluter.sh +63 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/root-cause-tracing.md +169 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-academic.md +14 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-1.md +58 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-2.md +68 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/systematic-debugging/test-pressure-3.md +69 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/test-driven-development/SKILL.md +379 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/test-driven-development/testing-anti-patterns.md +299 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/using-git-worktrees/SKILL.md +218 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/using-superpowers/SKILL.md +87 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/verification-before-completion/SKILL.md +139 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-plans/SKILL.md +116 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/SKILL.md +655 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/anthropic-best-practices.md +1150 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/examples/CLAUDE_MD_TESTING.md +189 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/graphviz-conventions.dot +172 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/persuasion-principles.md +187 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/render-graphs.js +168 -0
- frankcode-0.1.3/src/frankcode/skills/superpowers/writing-skills/testing-skills-with-subagents.md +384 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/SKILL.md +105 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/api-routes.md +238 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/auth-route-protection.md +192 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/auth-session-management.md +191 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/deploy-adapters.md +201 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/env-functions.md +211 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/err-server-errors.md +187 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/file-separation.md +152 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/mw-request-middleware.md +166 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/sf-create-server-fn.md +146 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/sf-input-validation.md +158 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-hydration-safety.md +187 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-prerender.md +199 -0
- frankcode-0.1.3/src/frankcode/skills/tanstack-start-best-practices/rules/ssr-streaming.md +201 -0
- frankcode-0.1.3/src/frankcode/skills/test-api-endpoint/SKILL.md +71 -0
- frankcode-0.1.3/src/frankcode/skills/test-api-endpoint/evals/evals.json +119 -0
- frankcode-0.1.3/src/frankcode/skills/upload-creative-templates/SKILL.md +144 -0
- frankcode-0.1.3/src/frankcode/skills/web-patterns/SKILL.md +321 -0
- frankcode-0.1.3/src/frankcode/skills/web-pr-validation-gate/SKILL.md +127 -0
- frankcode-0.1.3/src/frankcode/skills/worktree-enforcer/SKILL.md +250 -0
- frankcode-0.1.3/src/frankcode/skills/worktrunk-setup/SKILL.md +387 -0
- frankcode-0.1.3/src/frankcode/skills/write-skill/SKILL.md +225 -0
- frankcode-0.1.3/src/frankcode/skills/write-skill/references/description-examples.md +102 -0
- frankcode-0.1.3/src/frankcode/skills/write-skill/references/skill-template.md +86 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/PKG-INFO +1 -1
- frankcode-0.1.3/src/frankcode.egg-info/SOURCES.txt +143 -0
- frankcode-0.1.3/tests/unit/test_setup.py +34 -0
- frankcode-0.1.1/src/frankcode/cli.py +0 -69
- frankcode-0.1.1/src/frankcode.egg-info/SOURCES.txt +0 -26
- frankcode-0.1.1/tests/unit/test_setup.py +0 -27
- {frankcode-0.1.1 → frankcode-0.1.3}/.github/workflows/test.yml +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/.gitignore +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/LICENSE +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/README.md +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/setup.cfg +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/__init__.py +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/oh-my-opencode-slim.json +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/opencode-verify.json +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/opencode.json +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/configs/prompt-rules.json +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/environment.py +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/orchestrator.py +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode/utils.py +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/dependency_links.txt +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/entry_points.txt +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/requires.txt +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/src/frankcode.egg-info/top_level.txt +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/tests/conftest.py +0 -0
- {frankcode-0.1.1 → frankcode-0.1.3}/tests/unit/test_environment.py +0 -0
- {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*'
|
|
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
|
|
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
|
|
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,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
|
+
```
|