forgedock 1.2.0 → 1.4.0

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"