forgedock 1.2.0 → 1.3.0

package/templates/cross-repo-trigger.yml

@@ -0,0 +1,282 @@
+# ForgeDock Cross-Repo Trigger — Workflow Template
+#
+# Installation
+# ─────────────
+# Copy this file into your PARENT repo at:
+#   .github/workflows/cross-repo-trigger.yml
+#
+# When a PR merges in this repo, the workflow reads forge.yaml to find satellite
+# repos that have trigger_on_merge: true, checks whether touched files match each
+# satellite's trigger_paths globs, and creates a structured investigation issue in
+# every matching satellite repo.
+#
+# Token requirements
+# ──────────────────
+# GITHUB_TOKEN (provided automatically by GitHub Actions) only has write access
+# to THIS repo. To create issues in satellite repos you need a Personal Access
+# Token (PAT) with "issues: write" scope on each satellite repo:
+#
+#   Repo Settings → Secrets and variables → Actions → New repository secret
+#   Name:  FORGE_PAT
+#   Value: ghp_... (your PAT)
+#
+# The workflow uses FORGE_PAT when set; it falls back to GITHUB_TOKEN otherwise.
+# For same-org repos you may not need a PAT if GITHUB_TOKEN already has cross-repo
+# write access (org-level permission inheritance). Cross-org or private satellite
+# repos always require a PAT.
+#
+# forge.yaml configuration
+# ─────────────────────────
+# Each satellite that should receive cross-repo triggers must set trigger_on_merge:
+#
+#   repos:
+#     satellites:
+#       - prefix: "sdk"
+#         repo: "acme-org/acme-python-sdk"
+#         staging_branch: "main"
+#         local_path: "/home/youruser/projects/acme-python-sdk"
+#         trigger_on_merge: true
+#         trigger_paths:
+#           - "src/api/**"
+#           - "types/**"
+#         auto_run: false    # reserved — see ForgeDock docs for auto_run setup
+#
+# Fields:
+#   trigger_on_merge  — boolean; set true to enable triggering for this satellite
+#   trigger_paths     — list of glob strings (GitHub Actions glob syntax); trigger
+#                       fires only when at least one changed file matches; omit to
+#                       trigger on every merge
+#   auto_run          — boolean; reserved for future auto_run handler; currently no-op
+#
+# Limits and guards
+# ─────────────────
+# - Max 10 satellite issues created per merge event (rate limit guard)
+# - Circular dependency guard: skips satellites whose repo matches this repo
+# - Satellites with trigger_on_merge: false (or absent) are skipped
+# - If forge.yaml is absent, the workflow exits cleanly with an informational log
+
+name: ForgeDock Cross-Repo Trigger
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  trigger:
+    name: Fire cross-repo satellite triggers
+    runs-on: ubuntu-latest
+
+    # Only run when the PR was actually merged (not just closed)
+    if: github.event.pull_request.merged == true
+
+    permissions:
+      contents: read    # Required: read forge.yaml from checked-out repo
+      issues: write     # Required: fallback if this repo is a self-referencing satellite
+
+    env:
+      # Use FORGE_PAT when set (cross-repo access); fall back to GITHUB_TOKEN.
+      # Assign via env so it is available to all steps without repeating the expression.
+      FORGE_TOKEN: ${{ secrets.FORGE_PAT || github.token }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check forge.yaml exists
+        id: forge_check
+        run: |
+          if [ -f "forge.yaml" ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "forge.yaml found"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "forge.yaml not found — no satellite configuration to process. Exiting cleanly."
+          fi
+
+      - name: Parse forge.yaml and get changed files
+        id: forge_parse
+        if: steps.forge_check.outputs.exists == 'true'
+        env:
+          GH_TOKEN: ${{ env.FORGE_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          UPSTREAM_REPO: ${{ github.repository }}
+        run: |
+          # Get changed files from the merged PR
+          CHANGED_FILES_JSON=$(gh pr view "$PR_NUMBER" -R "$UPSTREAM_REPO" --json files --jq '[.files[].path]')
+          echo "Changed files: $CHANGED_FILES_JSON"
+          echo "changed_files_json=$CHANGED_FILES_JSON" >> "$GITHUB_OUTPUT"
+
+          # Parse satellite list from forge.yaml using Python3 (always available on ubuntu-latest)
+          SATELLITES_JSON=$(python3 -c "
+          import yaml, json, sys
+
+          try:
+              with open('forge.yaml', 'r') as f:
+                  config = yaml.safe_load(f)
+          except Exception as e:
+              print(json.dumps([]), end='')
+              sys.exit(0)
+
+          repos = config.get('repos', {}) or {}
+          satellites = repos.get('satellites', []) or []
+
+          result = []
+          for sat in satellites:
+              if not isinstance(sat, dict):
+                  continue
+              repo = sat.get('repo', '')
+              trigger_on_merge = sat.get('trigger_on_merge', False)
+              trigger_paths = sat.get('trigger_paths', []) or []
+              auto_run = sat.get('auto_run', False)
+              if not repo or not trigger_on_merge:
+                  continue
+              result.append({
+                  'repo': repo,
+                  'trigger_paths': trigger_paths,
+                  'auto_run': bool(auto_run),
+              })
+
+          print(json.dumps(result), end='')
+          ")
+          echo "Satellites with trigger_on_merge=true: $SATELLITES_JSON"
+          echo "satellites_json=$SATELLITES_JSON" >> "$GITHUB_OUTPUT"
+
+      - name: Fire satellite triggers
+        if: steps.forge_check.outputs.exists == 'true'
+        env:
+          GH_TOKEN: ${{ env.FORGE_TOKEN }}
+          UPSTREAM_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          MERGED_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          SATELLITES_JSON: ${{ steps.forge_parse.outputs.satellites_json }}
+          CHANGED_FILES_JSON: ${{ steps.forge_parse.outputs.changed_files_json }}
+        run: |
+          python3 -c "
+          import json, os, subprocess, sys, fnmatch
+
+          upstream_repo      = os.environ['UPSTREAM_REPO']
+          pr_number          = os.environ['PR_NUMBER']
+          merged_branch      = os.environ['MERGED_BRANCH']
+          pr_url             = os.environ['PR_URL']
+          pr_title           = os.environ['PR_TITLE']
+          satellites_json    = os.environ.get('SATELLITES_JSON', '[]')
+          changed_files_json = os.environ.get('CHANGED_FILES_JSON', '[]')
+
+          try:
+              satellites = json.loads(satellites_json) if satellites_json else []
+          except json.JSONDecodeError:
+              satellites = []
+
+          try:
+              changed_files = json.loads(changed_files_json) if changed_files_json else []
+          except json.JSONDecodeError:
+              changed_files = []
+
+          if not satellites:
+              print('No satellites with trigger_on_merge: true found in forge.yaml')
+              sys.exit(0)
+
+          if not changed_files:
+              print('No changed files found in merged PR — nothing to match against trigger_paths')
+              sys.exit(0)
+
+          def matches_glob(path, pattern):
+              if fnmatch.fnmatch(path, pattern):
+                  return True
+              if '**' not in pattern:
+                  return False
+              parts = pattern.split('**')
+              prefix = parts[0].rstrip('/')
+              suffix = parts[-1].lstrip('/')
+              if prefix and not path.startswith(prefix):
+                  return False
+              if suffix and not (fnmatch.fnmatch(path, suffix) or '/' + suffix in path):
+                  return False
+              return True
+
+          issues_created = 0
+          MAX_ISSUES = 10
+          NL = chr(10)
+
+          for sat in satellites:
+              if issues_created >= MAX_ISSUES:
+                  print(f'Rate limit reached: {MAX_ISSUES} satellite issues created. Stopping.')
+                  break
+
+              sat_repo      = sat.get('repo', '')
+              trigger_paths = sat.get('trigger_paths', [])
+              auto_run      = sat.get('auto_run', False)
+
+              if not sat_repo:
+                  continue
+
+              # Circular dependency guard
+              if sat_repo == upstream_repo:
+                  print(f'Skipping {sat_repo}: circular dependency guard (satellite == upstream repo)')
+                  continue
+
+              # Glob matching against trigger_paths
+              if trigger_paths:
+                  matched_files = [
+                      f for f in changed_files
+                      if any(matches_glob(f, p) for p in trigger_paths)
+                  ]
+                  if not matched_files:
+                      print(f'Skipping {sat_repo}: no changed files match trigger_paths {trigger_paths}')
+                      continue
+              else:
+                  matched_files = list(changed_files)
+                  print(f'{sat_repo}: no trigger_paths set — triggering on all {len(matched_files)} changed file(s)')
+
+              print(f'Creating issue in {sat_repo}: {len(matched_files)} matched file(s)')
+
+              matched_list = NL.join(f'- {f}' for f in matched_files)
+              auto_run_note = (
+                  NL + '> **auto_run** is set for this satellite. '
+                  'Run /work-on on this issue number to begin automated investigation.' + NL
+                  if auto_run else ''
+              )
+
+              issue_body = (
+                  '<!-- FORGE:CROSS_REPO_TRIGGER -->' + NL +
+                  '## Cross-Repo Trigger' + NL + NL +
+                  f'A PR merged in **{upstream_repo}** touches paths relevant to this satellite repo.' + NL + NL +
+                  '### Upstream Event' + NL +
+                  f'- Upstream repo: {upstream_repo}' + NL +
+                  f'- Merged PR: #{pr_number} ({pr_url})' + NL +
+                  f'- PR title: {pr_title}' + NL +
+                  f'- Merged branch: {merged_branch}' + NL + NL +
+                  '### Matched Files' + NL +
+                  f'These changed files matched this satellites trigger_paths:' + NL + NL +
+                  matched_list + NL + NL +
+                  '### Recommended Action' + NL +
+                  'Investigate whether these changes affect this satellite repos contracts, types, or integrations.' + NL + NL +
+                  f'Review the diff at {pr_url} or run /work-on on this issue to begin automated investigation.' + NL +
+                  auto_run_note + NL +
+                  '### Context' + NL +
+                  'Created automatically by the ForgeDock cross-repo trigger workflow.' + NL +
+                  'See https://github.com/RapierCraftStudios/ForgeDock for documentation.' + NL
+              )
+
+              issue_title = f'feat(cross-repo): upstream merge in {upstream_repo} (PR #{pr_number}) — investigate impact'
+
+              result = subprocess.run(
+                  ['gh', 'issue', 'create',
+                   '-R', sat_repo,
+                   '--title', issue_title,
+                   '--body', issue_body],
+                  capture_output=True, text=True
+              )
+
+              if result.returncode == 0:
+                  issue_url = result.stdout.strip()
+                  print(f'Created issue in {sat_repo}: {issue_url}')
+                  issues_created += 1
+              else:
+                  print(f'ERROR creating issue in {sat_repo}: {result.stderr.strip()}')
+                  print('Hint: Ensure FORGE_PAT has issues:write access to this satellite repo.')
+
+          print(f'Done: {issues_created} satellite issue(s) created.')
+          "

package/templates/cursor/forge.mdc

@@ -0,0 +1,148 @@
+---
+description: ForgeDock pipeline adapter for Cursor Agent mode
+alwaysApply: false
+---
+
+# ForgeDock Pipeline — Cursor Adapter
+
+This file is part of the [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) autonomous AI development pipeline. It adapts the ForgeDock pipeline for execution within Cursor's Agent mode.
+
+## What ForgeDock Is
+
+ForgeDock is a structured development pipeline that uses GitHub as a knowledge graph. Each pipeline phase (investigate → build → review → merge) writes machine-readable annotations (FORGE: HTML comments) to GitHub issue and PR comments. Downstream phases read those annotations to reconstruct context — without relying on conversation history.
+
+**Key principle**: GitHub issues/PRs are the persistent context layer. All state lives there, not in this conversation.
+
+## Prerequisites
+
+Before running any pipeline phase, verify these tools are available in the terminal:
+
+```bash
+gh auth status          # GitHub CLI — authenticated
+git --version           # Git — available
+```
+
+ForgeDock command specs live in the repo at `commands/` (if this repo uses ForgeDock) or are available globally after `npx forgedock` install.
+
+## Running the Pipeline
+
+### Start a Pipeline Run
+
+To work on a GitHub issue, invoke the `work-on` command spec directly:
+
+```bash
+# Read the full work-on spec first
+cat commands/work-on.md
+
+# Then execute the pipeline for issue #NUMBER following the spec exactly
+# Phase sequence: Phase 0 (load) → Phase 1 (investigate) → Phase 3 (build) → Phase 4 (PR) → Phase 5 (review) → Phase 6 (close)
+```
+
+**Critical**: After reading `commands/work-on.md`, follow the Universal Phase Dispatcher section exactly. Execute all phases in sequence — do not stop between phases unless a terminal label is set (`workflow:merged`, `workflow:invalid`, `needs-human`).
+
+### Load Issue Context
+
+```bash
+# Load issue state (always do this first — GitHub is the source of truth)
+gh issue view NUMBER -R OWNER/REPO --json number,title,body,labels,state,comments,milestone
+
+# Read existing pipeline annotations
+gh api repos/OWNER/REPO/issues/NUMBER/comments \
+  --jq '.[] | {id: .id, author: .user.login, body: .body}'
+```
+
+### Check Terminal State
+
+After every phase, check whether a terminal label is set before continuing:
+
+```bash
+gh issue view NUMBER -R OWNER/REPO --json labels --jq '[.labels[].name]'
+```
+
+**Terminal labels** (stop if any are present):
+- `workflow:merged`
+- `workflow:invalid`
+- `needs-human`
+- `workflow:decomposed`
+
+### Write FORGE Annotations
+
+Each pipeline phase writes a structured annotation to GitHub. Use exact format from `docs/FORGE-PROTOCOL.md`:
+
+```bash
+# Post investigation report (Phase 1C)
+gh issue comment NUMBER -R OWNER/REPO --body "<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+...
+<!-- INVESTIGATION:COMPLETE -->"
+
+# Post builder report (Phase 3M)
+gh issue comment NUMBER -R OWNER/REPO --body "<!-- FORGE:BUILDER -->
+## Implementation Complete
+...
+<!-- FORGE:BUILDER:COMPLETE -->"
+```
+
+### Git Workflow
+
+```bash
+# Create a worktree for the branch (Phase 3E)
+git fetch origin
+git worktree add .claude/worktrees/BRANCH_NAME -b BRANCH_NAME origin/STAGING_OR_MILESTONE_BRANCH
+
+# Commit changes (Phase 3K)
+cd .claude/worktrees/BRANCH_NAME
+git add -u
+git commit -m "feat(scope): description (#NUMBER)"
+
+# Push and create PR (Phase 4B-4D)
+git push -u origin BRANCH_NAME
+gh pr create -R OWNER/REPO --base PR_BASE --head BRANCH_NAME \
+  --title "Feat: description" --body "..."
+```
+
+### Labels
+
+ForgeDock uses `workflow:*` labels to track pipeline state:
+
+```bash
+# Transition labels as you progress through phases
+gh issue edit NUMBER -R OWNER/REPO --add-label "workflow:investigating"
+gh issue edit NUMBER -R OWNER/REPO --add-label "workflow:ready-to-build" --remove-label "workflow:investigating"
+gh issue edit NUMBER -R OWNER/REPO --add-label "workflow:building" --remove-label "workflow:ready-to-build"
+gh issue edit NUMBER -R OWNER/REPO --add-label "workflow:in-review" --remove-label "workflow:building"
+gh issue edit NUMBER -R OWNER/REPO --add-label "workflow:merged" --remove-label "workflow:in-review"
+```
+
+## Limitations vs. Claude Code
+
+| Capability | Claude Code | Cursor (this adapter) |
+|------------|-------------|----------------------|
+| Skill loading | Dynamic (`~/.claude/commands/`) | Static (this rules file) |
+| Multi-phase pipeline | Automatic (single session) | Manual (re-invoke agent per phase) |
+| Sub-skill invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
+| Session continuity | Native compaction resilience | Re-read GitHub state each invocation |
+
+**Multi-phase pipeline**: Cursor Agent mode does not persist between invocations. After each phase completes, you must manually re-invoke the agent for the next phase. The pipeline's compaction resilience (reading GitHub state at the start of each phase) handles this correctly — each new agent invocation re-reads the issue and picks up from the current label state.
+
+**Sub-skill invocation**: When the pipeline spec calls `Skill("review-pr")` or similar, read the referenced command spec file directly:
+
+```bash
+cat commands/review-pr.md  # Then follow the spec
+```
+
+## Configuration
+
+Your project's ForgeDock configuration is in `forge.yaml`. The pipeline reads `project.github.repo`, `project.github.owner`, and `branches.staging` from this file.
+
+```bash
+cat forge.yaml  # Review project configuration
+```
+
+## Reference
+
+- `commands/work-on.md` — Full pipeline spec (investigate → build → review → merge)
+- `commands/review-pr.md` — PR review spec
+- `commands/quality-gate.md` — Pre-commit quality checks
+- `docs/FORGE-PROTOCOL.md` — FORGE annotation protocol reference
+- `docs/CURSOR.md` — Cursor-specific installation and usage guide

package/templates/github-actions/forgedock-autopilot.yml

@@ -0,0 +1,113 @@
+# ForgeDock Autopilot — Scheduled Cron Workflow Template
+#
+# Copy this file into your repo at:
+#   .github/workflows/forgedock-autopilot.yml
+#
+# Required secrets (set in your repo's Settings → Secrets → Actions):
+#   ANTHROPIC_API_KEY   — Your Anthropic API key (https://console.anthropic.com)
+#
+# GITHUB_TOKEN is provided automatically by GitHub Actions.
+#
+# See docs/AUTOPILOT-CRON.md for full setup guide.
+
+name: ForgeDock Autopilot
+
+on:
+  schedule:
+    # Every Monday at 9 AM UTC — adjust to your preferred cadence
+    - cron: '0 9 * * 1'
+
+  workflow_dispatch:
+    # Manual trigger — allows you to run autopilot on demand with custom options
+    inputs:
+      mode:
+        description: 'Run mode: recon (safe, read-only) or fix (creates branches + PRs)'
+        required: false
+        default: 'recon'
+        type: choice
+        options:
+          - recon
+          - fix
+      limit:
+        description: 'Max issues to fix per run (fix mode only)'
+        required: false
+        default: '3'
+        type: string
+
+jobs:
+  autopilot:
+    name: Run /autopilot
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write        # Required: create branches, push commits (fix mode)
+      issues: write          # Required: create and label issues
+      pull-requests: write   # Required: create PRs (fix mode)
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Fetch full history so git log commands in /autopilot work correctly
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install ForgeDock
+        run: npx --yes forgedock
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Resolve autopilot arguments
+        id: args
+        env:
+          # Pass workflow_dispatch inputs through env: indirection rather than
+          # interpolating ${{ inputs.* }} directly into the run: script text.
+          # inputs.limit is free-text (type: string) — splicing it straight into
+          # the shell would let a crafted value break out of the assignment and
+          # inject arbitrary commands. inputs.mode is a `type: choice` enum and
+          # isn't exploitable the same way, but is routed the same way for
+          # consistency/defense-in-depth.
+          MODE_INPUT: ${{ inputs.mode }}
+          LIMIT_INPUT: ${{ inputs.limit }}
+        run: |
+          # On scheduled runs: always recon mode (safe default)
+          # On workflow_dispatch: use the selected mode input
+          if [ "${{ github.event_name }}" = "schedule" ]; then
+            MODE="recon"
+            LIMIT="3"
+          else
+            MODE="$MODE_INPUT"
+            LIMIT="$LIMIT_INPUT"
+          fi
+
+          if [ "$MODE" = "fix" ]; then
+            ARGS="--fix --limit $LIMIT"
+          else
+            ARGS="--recon-only"
+          fi
+
+          echo "mode=$MODE" >> "$GITHUB_OUTPUT"
+          echo "args=$ARGS" >> "$GITHUB_OUTPUT"
+          echo "Autopilot mode: $MODE (args: $ARGS)"
+
+      - name: Run /autopilot
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ github.token }}
+          # CI=true tells /autopilot Phase 4B to skip the interactive confirmation
+          # gate. The workflow_dispatch mode=fix input serves as the human opt-in.
+          CI: "true"
+          # AUTOPILOT_ARGS is derived (one step upstream) from the free-text
+          # inputs.limit workflow_dispatch input. Route it through env:
+          # indirection here too — splicing it directly via ${{ }} into this
+          # run: block would reopen the same script-injection vector one hop
+          # later, in a step that also carries ANTHROPIC_API_KEY/GH_TOKEN.
+          AUTOPILOT_ARGS: ${{ steps.args.outputs.args }}
+        run: |
+          claude --dangerously-skip-permissions \
+            -p "/autopilot $AUTOPILOT_ARGS"