Runjam Defaults

RunJam Default Constraints

These are non-negotiable defaults that apply to every session. They prevent common Agent mistakes: outputting files to wrong directories, using unavailable dependencies without a fallback, and making assumptions about the environment.

Treat every rule below as a HARD RULE — violating any one means the task is not done, regardless of content quality.

0. Path Convention (READ FIRST — prevents the #1 Agent mistake)

Every relative path in this document and in every skill's SKILL.md is relative to the SESSION WORKING DIRECTORY — NOT the skill's own directory.

This session's working directory (absolute path)

/Users/hekun/work/code/runjam

The Agent process was started with this directory as its cwd. Every relative path below resolves relative to it. If pwd disagrees with the absolute path above, trust the absolute path above and cd to it first — it is the authoritative session root for this session.

The rule

When a SKILL.md says ./outputs/ or ./workspace/, it means:

<session working directory>/outputs/      ← deliverables go HERE
<session working directory>/workspace/    ← helper scripts go HERE

NOT:

<session working directory>/.claude/skills/<skill-name>/outputs/     ← WRONG
<session working directory>/.claude/skills/<skill-name>/workspace/   ← WRONG

Path safety check (MANDATORY in every generated script)

At the top of any Python script you generate, include this guard to ensure outputs land in the session root, not inside a skill folder:

import os
# Ensure we're writing to the session working directory, not a skill folder.
# If the cwd contains '.claude/skills' or '.codex/skills' or '.gemini/skills',
# walk up to the session root (the parent of the .claude/.codex/.gemini dir).
_cwd = os.getcwd()
for _marker in ('.claude', '.codex', '.gemini'):
    _idx = _cwd.find(os.sep + _marker + os.sep + 'skills')
    if _idx != -1:
        os.chdir(_cwd[:_idx])  # session root = parent of .claude/.codex/.gemini
        break
SESSION_ROOT = os.getcwd()
OUTPUTS_DIR  = os.path.join(SESSION_ROOT, 'outputs')
WORKSPACE_DIR = os.path.join(SESSION_ROOT, 'workspace')
os.makedirs(OUTPUTS_DIR, exist_ok=True)
os.makedirs(WORKSPACE_DIR, exist_ok=True)

Then use OUTPUTS_DIR (an absolute path) for all deliverable paths:

OUTPUT_PATH = os.path.join(OUTPUTS_DIR, "report.pptx")  # ✅ absolute, session-root
# NOT: "./outputs/report.pptx"  ← ambiguous, may land in skill dir

Quick self-test before running a script

pwd                                    # should show session root, NOT .../skills/<name>
# If pwd contains 'skills/', you are in the wrong directory. cd to session root first.
mkdir -p ./outputs ./workspace         # creates in session root

1. Output Path Convention

All generated files (documents, images, presentations, archives, scripts written for the user's deliverable) MUST be placed in the session working directory's outputs/ folder — NOT inside any skill directory.

Before creating any output file:

mkdir -p ./outputs   # run from session root (see §0)

Acceptable (all relative to session working directory):

• ./outputs/report.pptx
• ./outputs/chart.png
• ./outputs/data.xlsx
• ./outputs/exported-doc.pdf

Not acceptable:

• ./report.pptx (in session root directly)
• ~/Desktop/report.pptx (user home)
• ./tmp/result.pptx (random subdir)
• .claude/skills/<skill-name>/outputs/report.pptx (inside skill directory — FORBIDDEN)
• Any arbitrary path outside ./outputs/ unless it's part of the project's own code structure.

Exception: Code files that belong to the project (e.g. under ./src/, ./components/, ./tests/) follow the project's existing conventions. Config files at project root (e.g. tsconfig.json, vite.config.ts) are also fine.

Verification step: After producing a deliverable file, run from the session root:

ls -la ./outputs/<filename>

and confirm the file exists and has non-zero size. If the file is not there, check whether it accidentally landed inside .claude/skills/*/outputs/ — if so, move it to the session root's ./outputs/ and fix your script.

2. Dependency Check Before Action

Before using any skill, library, or CLI tool, check that its dependencies are actually available.

Quick dependency probe recipes

Decision matrix

Golden rule: read before you write. If the skill has a SKILL.md header note, dependency check step, or setup section — read and run it first. Do not skip setup steps.

3. Fallback Strategy

When a primary workflow is unavailable:

1. Check the skill's SKILL.md for a documented fallback. If present, use it verbatim.
2. Check if an equivalent built-in tool/skill is available. For example:
   • No image-generation skill → use python-pptx for text-based slides (all text editable, often the better choice for reports anyway).
   • No officecli → use python-pptx / python-docx / openpyxl for Office documents.
   • No dedicated PDF skill → check if pypdf / reportlab Python packages are available.
3. No clear alternative → tell the user explicitly. Say:

   "I need X to do Y, but X is not available. Options: (a) install X, (b) use alternative Z that I have available, or (c) tell me another plan."

Never silently switch approaches without telling the user what changed and why. A one-sentence note is required.