@aion0/forge 0.5.26 → 0.5.27

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/05-pipelines.md

@@ -0,0 +1,460 @@
+# Pipelines (Workflows)
+
+## What Are Pipelines?
+
+Pipelines chain multiple tasks into a DAG (directed acyclic graph). Each step can depend on previous steps, pass outputs forward, and run in parallel. Pipelines are defined as YAML workflow files.
+
+## YAML Workflow Format
+
+```yaml
+name: my-workflow
+description: "What this workflow does"
+input:
+  feature: "Feature description"      # required input fields
+  priority: "Priority level (optional)"
+vars:
+  project: my-app                     # default variables
+nodes:
+  design:
+    project: "{{vars.project}}"
+    prompt: "Design: {{input.feature}}"
+    outputs:
+      - name: spec
+        extract: result
+  implement:
+    project: "{{vars.project}}"
+    depends_on: [design]
+    prompt: "Implement based on: {{nodes.design.outputs.spec}}"
+    outputs:
+      - name: diff
+        extract: git_diff
+  review:
+    project: "{{vars.project}}"
+    depends_on: [implement]
+    prompt: "Review the changes"
+```
+
+## Node Options
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `project` | Project name (supports templates) | required |
+| `prompt` | Claude Code prompt or shell command | required |
+| `mode` | `claude` (AI agent) or `shell` (raw command) | `claude` |
+| `branch` | Auto-checkout branch before running (supports templates) | none |
+| `depends_on` | List of node IDs that must complete first | `[]` |
+| `outputs` | Extract results (see Output Extraction) | `[]` |
+| `routes` | Conditional routing to next nodes (see Routing) | `[]` |
+| `max_iterations` | Max loop iterations for routed nodes | `3` |
+
+## Node Modes
+
+### `claude` (default)
+Runs the prompt via Claude Code (`claude -p`). The AI agent reads the codebase, makes changes, and returns a result.
+
+### `shell`
+Runs the prompt as a raw shell command (`bash -c "..."`). Useful for git operations, CLI tools, API calls, etc.
+
+```yaml
+nodes:
+  setup:
+    mode: shell
+    project: my-app
+    prompt: |
+      git checkout main && git pull && echo "READY"
+    outputs:
+      - name: info
+        extract: stdout
+```
+
+**Shell escaping**: Template values in shell mode are automatically escaped (single quotes `'` → `'\''`) to prevent injection.
+
+## Template Variables
+
+Templates use `{{...}}` syntax and are resolved before execution:
+
+- `{{input.xxx}}` — pipeline input values provided at trigger time
+- `{{vars.xxx}}` — workflow-level variables defined in YAML
+- `{{nodes.<node_id>.outputs.<output_name>}}` — outputs from completed nodes
+
+Node IDs can contain hyphens (e.g., `{{nodes.fetch-issue.outputs.data}}`).
+
+### Examples
+
+```yaml
+prompt: "Fix issue #{{input.issue_id}} in {{input.project}}"
+prompt: "Based on: {{nodes.design.outputs.spec}}"
+prompt: |
+  REPO={{nodes.setup.outputs.repo}} && \
+  gh pr create --title "Fix #{{input.issue_id}}" -R "$REPO"
+```
+
+## Output Extraction
+
+Each node can extract outputs for downstream nodes:
+
+| Extract Type | Description |
+|-------------|-------------|
+| `result` | Claude's final response text |
+| `stdout` | Shell command stdout (same as result for shell mode) |
+| `git_diff` | Git diff of changes made during the task |
+
+```yaml
+outputs:
+  - name: summary
+    extract: result
+  - name: changes
+    extract: git_diff
+```
+
+## Skip Convention (`__SKIP__`)
+
+If a shell node outputs `__SKIP__` in its stdout and exits with code 0, the node is marked as `skipped` instead of `done`. All downstream dependent nodes are also skipped. The pipeline completes successfully (not failed).
+
+```yaml
+nodes:
+  check:
+    mode: shell
+    project: my-app
+    prompt: |
+      if [ -z "{{input.issue_id}}" ]; then
+        echo "__SKIP__ No issue_id provided"
+        exit 0
+      fi
+      echo "Processing issue {{input.issue_id}}"
+```
+
+Use this for optional steps that should gracefully skip when preconditions aren't met.
+
+## Conditional Routing
+
+Nodes can route to different next steps based on output content:
+
+```yaml
+nodes:
+  analyze:
+    project: my-app
+    prompt: "Analyze the issue. Reply SIMPLE or COMPLEX."
+    outputs:
+      - name: complexity
+        extract: result
+    routes:
+      - condition: "{{outputs.complexity contains 'SIMPLE'}}"
+        next: quick-fix
+      - condition: default
+        next: deep-fix
+  quick-fix:
+    depends_on: [analyze]
+    project: my-app
+    prompt: "Apply a quick fix"
+  deep-fix:
+    depends_on: [analyze]
+    project: my-app
+    prompt: "Do a thorough analysis and fix"
+```
+
+### Route Conditions
+
+- `{{outputs.<name> contains '<keyword>'}}` — check if output contains a keyword
+- `default` — fallback route (always matches)
+
+### Loops
+
+If a route points back to the same node, it creates a loop (up to `max_iterations`):
+
+```yaml
+nodes:
+  fix-and-test:
+    project: my-app
+    prompt: "Fix the failing test, then run tests."
+    max_iterations: 5
+    outputs:
+      - name: test_result
+        extract: result
+    routes:
+      - condition: "{{outputs.test_result contains 'PASS'}}"
+        next: done
+      - condition: default
+        next: fix-and-test   # loop back to retry
+  done:
+    depends_on: [fix-and-test]
+    mode: shell
+    project: my-app
+    prompt: "echo 'All tests passing!'"
+```
+
+## Branch Auto-checkout
+
+Pipeline steps automatically use **git worktree** for isolated execution. Each step gets its own working copy — your main working directory is never affected.
+
+```yaml
+nodes:
+  work:
+    project: my-app
+    branch: "feature/{{input.feature_name}}"   # optional: custom branch name
+    prompt: "Implement the feature"
+```
+
+**How it works:**
+- If `branch` is specified, a worktree is created at `<project>/.forge/worktrees/<branch>/`
+- If `branch` is omitted, an auto-generated branch `pipeline/<id>` is used
+- **All step modes** (shell, agent, prompt, plugin) run inside the worktree
+- After completion, the worktree is preserved for review
+- Clean up: `git worktree remove <path>` after reviewing changes
+
+**Shell steps in worktree:**
+
+Shell steps receive 3 environment variables for worktree context:
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `FORGE_WORKTREE` | Worktree path (current working directory) | `/project/.forge/worktrees/pipeline-abc12345` |
+| `FORGE_WORKTREE_BRANCH` | Branch name for this worktree | `pipeline/abc12345` or `feature/my-feature` |
+| `FORGE_PROJECT_ROOT` | Original project root path | `/Users/me/projects/my-app` |
+
+Use these when shell scripts need to reference the original repo:
+
+```yaml
+nodes:
+  push-changes:
+    mode: shell
+    prompt: |
+      git add -A && git commit -m "Pipeline changes" &&
+      git push origin "$FORGE_WORKTREE_BRANCH"
+```
+
+To operate on the original repo from a shell step:
+```yaml
+  check-main:
+    mode: shell
+    prompt: |
+      cd "$FORGE_PROJECT_ROOT" && git log --oneline -5
+```
+
+**Benefits:**
+- Your working directory stays clean during pipeline execution
+- Multiple pipelines can run in parallel on the same project
+- Changes are isolated on branches, easy to review/merge/discard
+- All step modes use the same isolation — consistent behavior
+
+## Parallel Execution
+
+Nodes without dependency relationships run in parallel:
+
+```yaml
+nodes:
+  frontend:
+    project: my-app
+    prompt: "Build frontend component"
+  backend:
+    project: my-app
+    prompt: "Build API endpoint"
+  integration:
+    depends_on: [frontend, backend]  # waits for both
+    project: my-app
+    prompt: "Integration test"
+```
+
+`frontend` and `backend` run simultaneously; `integration` starts when both finish.
+
+## Built-in Workflows
+
+### issue-fix-and-review
+Complete issue resolution: fetch GitHub issue → fix code on new branch → create PR.
+
+**Input**: `issue_id`, `project`, `base_branch` (optional), `extra_context` (optional)
+
+**Steps**: setup → fetch-issue → fix-code → push-and-pr → notify
+
+**Prerequisites**: `gh` CLI installed and authenticated (`gh auth login`), project has GitHub remote.
+
+### pr-review
+Review a pull request: fetch PR diff → AI review → report.
+
+**Input**: `pr_number`, `project`
+
+**Steps**: setup → fetch-pr → review → post-review
+
+## Project Pipeline Bindings
+
+Projects can bind workflows for easy access and scheduled execution.
+
+### Binding a Workflow to a Project
+
+1. Go to **Projects → select project → Pipelines tab**
+2. Click **+ Add** to attach a workflow
+3. Configure:
+   - **Enabled**: toggle on/off
+   - **Schedule**: Manual only, or periodic (15min to 24h intervals)
+4. Click **Run** to manually trigger
+
+### Scheduled Execution
+
+When a schedule is set (e.g., "Every 30 min"):
+- The scheduler checks all bindings every 60 seconds
+- If the interval has elapsed since last run, the pipeline triggers automatically
+- Running pipelines are not re-triggered (prevents overlap)
+- `Last run` and `Next run` times are shown in the UI
+
+Schedule options: Manual only, 15min, 30min, 1h, 2h, 6h, 12h, 24h.
+
+### API
+
+```bash
+# List bindings + runs + workflows for a project
+curl "http://localhost:8403/api/project-pipelines?project=/path/to/project"
+
+# Add binding
+curl -X POST http://localhost:8403/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"add","projectPath":"/path","projectName":"my-app","workflowName":"issue-fix-and-review"}'
+
+# Update binding (enable/disable, change config/schedule)
+curl -X POST http://localhost:8403/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"update","projectPath":"/path","workflowName":"issue-fix-and-review","config":{"interval":30}}'
+
+# Trigger pipeline manually
+curl -X POST http://localhost:8403/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"trigger","projectPath":"/path","projectName":"my-app","workflowName":"issue-fix-and-review","input":{"issue_id":"42"}}'
+
+# Remove binding
+curl -X POST http://localhost:8403/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"remove","projectPath":"/path","workflowName":"issue-fix-and-review"}'
+```
+
+## CLI
+
+```bash
+forge flows              # list available workflows
+forge run my-workflow    # execute a workflow
+```
+
+## Import a Workflow
+
+1. In **Pipelines** tab, click **Import**
+2. Paste YAML workflow content
+3. Click **Save Workflow**
+
+Or save YAML directly to `~/.forge/data/flows/<name>.yaml`.
+
+To create a workflow via Help AI: ask "Create a pipeline that does X" — the AI will generate the YAML for you to import.
+
+## Creating Workflows via API
+
+```bash
+curl -X POST http://localhost:8403/api/pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action": "save-workflow", "yaml": "<yaml content>"}'
+```
+
+## Conversation Mode (Multi-Agent Dialogue)
+
+Conversation mode enables multiple agents to collaborate through structured dialogue. Instead of a DAG of tasks, Forge acts as a message broker — sending prompts between agents in rounds until a stop condition is met.
+
+### YAML Format
+
+```yaml
+name: architect-implementer
+type: conversation
+description: "Architect designs, implementer builds"
+input:
+  project: "Project name"
+  task: "What to build"
+agents:
+  - id: architect
+    agent: claude
+    role: "You are a software architect. Design the solution, define interfaces, and review implementations."
+  - id: implementer
+    agent: codex
+    role: "You are a developer. Implement what the architect designs."
+max_rounds: 10
+stop_condition: "both agents say DONE"
+initial_prompt: "Build: {{input.task}}"
+```
+
+### Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `type` | Must be `conversation` | required |
+| `agents` | List of participating agents | required |
+| `agents[].id` | Logical ID within conversation | required |
+| `agents[].agent` | Agent registry ID (`claude`, `codex`, `aider`, etc.) | `claude` |
+| `agents[].role` | System prompt / role description | none |
+| `agents[].project` | Project context (overrides input.project) | none |
+| `max_rounds` | Maximum number of full rounds | `10` |
+| `stop_condition` | When to stop early | none |
+| `initial_prompt` | The seed prompt (supports `{{input.*}}` templates) | required |
+| `context_strategy` | How to pass history between agents: `full`, `window`, `summary` | `summary` |
+| `context_window` | Number of recent messages to include in full (for `window`/`summary`) | `4` |
+| `max_content_length` | Truncate each message to this many characters | `3000` |
+
+### Context Strategies
+
+Agents don't share memory — Forge acts as broker and decides what context to forward.
+
+- **`summary`** (default): Older messages are compressed to one-line summaries. The most recent N messages (set by `context_window`) are passed in full. Best balance of context quality and token usage.
+- **`window`**: Only the last N messages are passed, older ones are dropped entirely. Lowest token usage.
+- **`full`**: All messages from all rounds are passed in full (each truncated to `max_content_length`). Most context but token-heavy.
+
+### Execution Flow
+
+1. Forge sends `initial_prompt` + role to the first agent
+2. Agent responds → Forge collects the response
+3. Forge builds context (per `context_strategy`) and sends to the next agent
+4. Repeat through all agents = 1 round
+5. Continue rounds until `stop_condition` or `max_rounds`
+
+### Stop Conditions
+
+- `"any agent says DONE"` — stops when any agent includes "DONE" in its response
+- `"both agents say DONE"` / `"all agents say DONE"` — stops when all agents have said "DONE"
+- If no stop condition, runs until `max_rounds`
+
+### UI
+
+Conversation pipelines show a chat-like view with color-coded agent bubbles, round numbers, and linked task IDs. The sidebar shows round progress (e.g., R3/10).
+
+### Example: Code Review Dialogue
+
+```yaml
+name: review-dialogue
+type: conversation
+description: "Two agents discuss code quality"
+input:
+  project: "Project name"
+  pr_number: "PR number to review"
+agents:
+  - id: reviewer
+    agent: claude
+    role: "You are a code reviewer. Find bugs, security issues, and suggest improvements."
+  - id: author
+    agent: claude
+    role: "You are the code author. Address review feedback, explain design decisions, and fix issues."
+max_rounds: 5
+stop_condition: "all agents say DONE"
+initial_prompt: "Review PR #{{input.pr_number}} in project {{input.project}}. Reviewer: analyze the diff. Author: be ready to address feedback."
+```
+
+## Pipeline Model
+
+In **Settings → Pipeline Model**, you can select which Claude model runs pipeline tasks. Set to `default` to use the same model as regular tasks.
+
+## Storage
+
+- Workflow YAML: `~/.forge/data/flows/`
+- Execution state: `~/.forge/data/pipelines/`
+- Binding config & run history: SQLite database (`~/.forge/data/forge.db`)
+
+## Tips for Writing Workflows
+
+1. **Start with shell nodes** for setup (git checkout, environment checks)
+2. **Use `__SKIP__`** for optional steps with precondition checks
+3. **Extract outputs** to pass data between nodes
+4. **Use routes** for conditional logic (simple/complex paths, retry loops)
+5. **Keep prompts focused** — each node should do one thing well
+6. **Test manually first** before setting up schedules
+7. **Use `depends_on`** to control execution order; nodes without dependencies run in parallel

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/06-skills.md

@@ -0,0 +1,43 @@
+# Skills Marketplace
+
+## Overview
+
+Browse, install, and manage Claude Code skills and commands from the Forge Skills registry.
+
+## Types
+
+| | Skills | Commands |
+|---|---|---|
+| Location | `~/.claude/skills/<name>/` | `~/.claude/commands/<name>.md` |
+| Entry file | `SKILL.md` | Single `.md` file |
+| Complexity | Multi-file with templates | Simple slash command |
+
+Both register as `/slash-command` in Claude Code.
+
+## Install
+
+1. Go to **Skills** tab in Forge
+2. Click **Sync** to fetch latest registry
+3. Click **Install** on any skill → choose Global or specific project
+4. Use in Claude Code with `/<skill-name>`
+
+## Update
+
+Skills with newer versions show a yellow "update" indicator. Click to update (checks for local modifications first).
+
+## Local Skills
+
+The **Local** tab shows skills/commands installed on your machine (both from marketplace and manually created). You can:
+- **Install to...** — Copy a local skill to another project or global
+- **Delete** — Remove from project or global
+- **Edit** — View and modify installed files
+
+## Registry
+
+Default: `https://raw.githubusercontent.com/aiwatching/forge-skills/main`
+
+Change in Settings → Skills Repo URL.
+
+## Custom Skills
+
+Create your own: put a `.md` file in `<project>/.claude/commands/` or a directory in `<project>/.claude/skills/<name>/`.

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/07-projects.md

@@ -0,0 +1,73 @@
+# Projects
+
+## Setup
+
+Add project directories in Settings → **Project Roots** (e.g. `~/Projects`). Forge scans subdirectories automatically.
+
+## Features
+
+### Code Tab
+- File tree browser
+- Syntax-highlighted code viewer
+- Git diff view (click changed files)
+- Git operations: commit, push, pull
+- Commit history
+
+### Skills & Commands Tab
+- View installed skills/commands for this project
+- Scope indicator: G (global), P (project), G+P (both)
+- Edit files, update from marketplace, uninstall
+
+### CLAUDE.md Tab
+- View and edit project's CLAUDE.md
+- Apply rule templates (built-in or custom)
+- Templates auto-injected with dedup markers
+
+### Issues Tab
+- Enable GitHub Issue Auto-fix per project
+- Configure scan interval and label filters
+- Manual trigger: enter issue # and click Fix Issue
+- Processed issues history with retry/delete
+- Auto-chains: fix → create PR → review
+
+### Workspace Tab
+- Configure multi-agent workspace (Forge Smiths)
+- Add smiths with roles, steps, and dependencies
+- Start/stop daemon, monitor execution
+- See [Workspace documentation](11-workspace.md) for details
+
+## Favorites
+
+Click ★ next to a project to favorite it. Favorites appear at the top of the sidebar.
+
+## Terminal
+
+### Opening a Terminal
+
+There are two ways to open a terminal for a project:
+
+**1. Project Header Button**
+- Click **Terminal** in the project header → opens with default agent (claude)
+- Click **▾** dropdown to select a different agent or profile
+- If the agent supports sessions (claude-code), a dialog shows: New Session / Resume Latest / Browse Sessions
+- Non-session agents (codex, aider) open directly
+
+**2. Terminal Tab "+" Button**
+- Click **+** in the terminal tab bar → select a project root → expand to see projects
+- Click an agent button (C = Claude, X = Codex, A = Aider, ● = Profile) to open
+- The terminal launches with the agent's configured env vars and model
+
+### Agent & Profile Selection
+
+When selecting an agent or profile for a terminal:
+- **Base agents** (Claude, Codex, Aider): Use their default configuration
+- **Profiles** (e.g., Forti K2, Claude Opus): Apply the profile's environment variables and model override
+- Environment variables are exported in the terminal before launching the CLI
+- Model is passed via `--model` flag (for claude-code agents)
+
+### Terminal Features
+- Full xterm.js terminal with tmux session persistence
+- Split panes (horizontal/vertical)
+- Multiple tabs per project
+- Tab state preserved across page refreshes
+- Tabs can be renamed and reordered

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/08-rules.md

@@ -0,0 +1,53 @@
+# Rules (CLAUDE.md Templates)
+
+## What Are Rules?
+
+Reusable markdown snippets that get appended to project CLAUDE.md files. They define coding conventions, security rules, workflow guidelines, etc.
+
+## Built-in Templates
+
+| Template | Description |
+|----------|-------------|
+| TypeScript Rules | Coding conventions (const, types, early returns) |
+| Git Workflow | Commit messages, branch naming |
+| Obsidian Vault | Vault integration instructions |
+| Security Rules | OWASP guidelines, no hardcoded secrets |
+
+## Manage Rules
+
+**Skills tab → Rules sub-tab**:
+- View all templates (built-in + custom)
+- Create new: click "+ New"
+- Edit any template (including built-in)
+- Delete custom templates
+- Set as "default" — auto-applied to new projects
+- Batch apply: select template → check projects → click "Apply"
+
+## Apply to Project
+
+**Project → CLAUDE.md tab**:
+- Left sidebar shows CLAUDE.md content + template list
+- Click "+ add" to inject a template
+- Click "added" to remove
+- Templates wrapped in `<!-- forge:template:id -->` markers (prevents duplicate injection)
+
+## Default Templates
+
+Templates marked as "default" are automatically injected into new projects when they first appear in the project list.
+
+## Custom Templates
+
+Stored in `~/.forge/data/claude-templates/`. Each is a `.md` file with YAML frontmatter:
+
+```markdown
+---
+name: My Rule
+description: What this rule does
+tags: [category]
+builtin: false
+isDefault: false
+---
+
+## My Custom Rule
+Your content here...
+```

package/.forge/worktrees/pipeline-4dd8dc2d/lib/help-docs/09-issue-autofix.md

@@ -0,0 +1,55 @@
+# Issue Auto-fix
+
+## Overview
+
+Automatically scan GitHub Issues, fix code, create PRs — all hands-free. Uses the built-in `issue-fix-and-review` pipeline workflow with integrated issue scanning.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated: `gh auth login`
+- Project has a GitHub remote
+
+## Setup
+
+1. Go to **Projects → select project → Pipelines tab**
+2. Click **+ Add** and select `issue-fix-and-review`
+3. Enable the binding
+4. Check **Auto-scan GitHub Issues** to enable automatic scanning
+5. Configure:
+   - **Schedule**: How often to scan (e.g., Every 30 min)
+   - **Labels**: Filter issues by label (comma-separated, empty = all)
+   - **Base Branch**: Leave empty for auto-detect (main/master)
+6. Click **Scan** to manually trigger a scan
+
+## Flow
+
+```
+Scan Issues → For each new issue:
+  Setup → Fetch Issue → Fix Code (new branch) → Push & Create PR → Notify
+```
+
+1. **Scan**: `gh issue list` finds open issues matching labels
+2. **Dedup**: Already-processed issues are skipped (tracked in `pipeline_runs`)
+3. **Setup**: Checks for clean working directory, detects repo and base branch
+4. **Fetch Issue**: `gh issue view` fetches issue data
+5. **Fix Code**: Claude analyzes issue and fixes code on `fix/<id>-<description>` branch
+6. **Push & PR**: Pushes branch and creates Pull Request via `gh pr create`
+7. **Notify**: Switches back to original branch, reports PR URL
+
+## Manual Trigger
+
+- **Run** button: Triggers the workflow with custom input (requires `issue_id`)
+- **Scan** button: Scans for all open issues and triggers fixes for new ones
+
+## Dedup
+
+Each processed issue is tracked with a `dedup_key` (e.g., `issue:42`) in the pipeline runs table. Once an issue has been processed, it won't be triggered again even if it's still open. To re-process an issue, delete its run from the execution history.
+
+## Safety
+
+- Checks for uncommitted changes before starting (aborts if dirty)
+- Always works on new branches (never modifies main/master)
+- Cleans up old fix branches for the same issue
+- Switches back to original branch after completion
+- Uses `--force-with-lease` for safe push
+- Running pipelines are not re-triggered (one fix per issue at a time)