forge-workflow 0.0.2 → 0.0.4

package/docs/BEADS_GITHUB_SYNC.md

@@ -0,0 +1,251 @@
+# GitHub <-> Beads Issue Sync
+
+Automatic synchronization between GitHub Issues and Beads issue tracking.
+
+**GitHub Issues** = human/team/public interface.
+**Beads** = AI agent engine (`bd ready`, `bd close`).
+
+Neither side needs to know about the other. Contributors file issues on GitHub; AI agents pick up work via Beads. Status changes propagate automatically.
+
+---
+
+## Architecture
+
+### Phase 1: GitHub -> Beads (CI-driven)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant GH as GitHub Issues
+    participant WF as GitHub Actions
+    participant BD as Beads CLI
+    participant Repo as .beads/ + mapping
+
+    U->>GH: Opens issue #42
+    GH->>WF: issues.opened trigger
+    WF->>WF: Guard checks (bot? skip label? no-beads?)
+    WF->>WF: Idempotency check (existing bot comment?)
+    WF->>BD: bd create --title "..." --type bug --priority 1
+    BD->>Repo: Write .beads/issues.jsonl
+    WF->>Repo: Write .github/beads-mapping.json {"42": "forge-abc"}
+    WF->>GH: Post bot comment <!-- beads-sync:42 -->
+    WF->>Repo: git commit + push
+
+    U->>GH: Closes issue #42
+    GH->>WF: issues.closed trigger
+    WF->>Repo: Read mapping: "42" -> "forge-abc"
+    WF->>BD: bd close forge-abc --reason "Closed via GitHub #42"
+    WF->>Repo: git commit + push
+```
+
+### Phase 2: Beads -> GitHub (push-triggered)
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Agent
+    participant BD as Beads CLI
+    participant Repo as .beads/
+    participant WF as GitHub Actions
+    participant GH as GitHub Issues
+
+    AI->>BD: bd close forge-abc
+    BD->>Repo: Update issues.jsonl
+    AI->>Repo: git push
+    Repo->>WF: push trigger (paths: .beads/**)
+    WF->>WF: Guard: skip if commit msg starts with "chore(beads):"
+    WF->>Repo: Diff issues.jsonl for closed transitions
+    WF->>GH: gh api PATCH /issues/42 state=closed
+```
+
+### Loop Prevention
+
+Three guards prevent infinite ping-pong:
+
+1. **Bot detection** -- workflows skip events from `github-actions[bot]`
+2. **Commit message prefix** -- Phase 2 workflow skips commits starting with `chore(beads):`
+3. **Opt-out label** -- `skip-beads-sync` label on any issue disables sync entirely
+
+---
+
+## Setup
+
+### Via Forge Setup (recommended)
+
+```bash
+bunx forge setup
+# During interactive prompts:
+# "Enable GitHub <-> Beads sync? (y/n)" -> y
+```
+
+This scaffolds:
+- `.github/workflows/github-to-beads.yml`
+- `.github/workflows/beads-to-github.yml` (Phase 2)
+- `.github/beads-mapping.json`
+- `scripts/github-beads-sync/` (Node modules)
+- `scripts/github-beads-sync.config.json`
+
+### Manual Setup
+
+1. Copy workflow files from `templates/` into `.github/workflows/`
+2. Copy `scripts/github-beads-sync/` and `scripts/github-beads-sync.config.json`
+3. Create `.github/beads-mapping.json` with `{}`
+4. Ensure Beads is initialized: `bd init`
+5. Commit and push to enable the workflows
+
+---
+
+## Configuration Reference
+
+All settings live in `scripts/github-beads-sync.config.json`.
+
+### Label and Type Mapping
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `labelToType` | `object` | `{"bug":"bug", "enhancement":"feature", "documentation":"task", "question":"task"}` | Maps GitHub labels to Beads issue types. First matching label wins. |
+| `labelToPriority` | `object` | `{"P0":0, "critical":0, "P1":1, "high":1, "P2":2, "medium":2, "P3":3, "low":3, "P4":4, "backlog":4}` | Maps GitHub labels to Beads priority levels (0-4). First matching label wins. |
+| `defaultType` | `string` | `"task"` | Beads type when no label matches `labelToType`. |
+| `defaultPriority` | `number` | `2` | Beads priority when no label matches `labelToPriority`. |
+| `mapAssignee` | `boolean` | `true` | Whether to copy GitHub assignee to Beads issue on creation. |
+
+### Security Gates (Public Repos)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `publicRepoGate` | `string` | `"none"` | Access control for public repos. See [Security](#security) section. |
+| `gateLabelName` | `string` | `"beads-track"` | Required label when `publicRepoGate` is `"label"`. |
+| `gateAssociations` | `string[]` | `["MEMBER", "COLLABORATOR", "OWNER"]` | Allowed author associations when `publicRepoGate` is `"author_association"`. |
+
+### Example: Custom Configuration
+
+```json
+{
+  "labelToType": {
+    "bug": "bug",
+    "feature": "feature",
+    "chore": "chore",
+    "spike": "task"
+  },
+  "labelToPriority": {
+    "urgent": 0,
+    "important": 1,
+    "normal": 2,
+    "nice-to-have": 3
+  },
+  "defaultType": "task",
+  "defaultPriority": 2,
+  "mapAssignee": true,
+  "publicRepoGate": "author_association",
+  "gateAssociations": ["MEMBER", "COLLABORATOR", "OWNER"]
+}
+```
+
+---
+
+## Security
+
+### Public Repo Gate
+
+On public repos, anyone can open an issue -- which triggers a commit to your default branch via the sync workflow. The `publicRepoGate` setting controls who can trigger sync:
+
+| Value | Behavior | Recommended For |
+|-------|----------|-----------------|
+| `"none"` | All issues sync (default). | Private repos, trusted teams. |
+| `"author_association"` | Only issues from authors in `gateAssociations` sync. | Public repos with known contributors. |
+| `"label"` | Only issues with the `gateLabelName` label sync. A maintainer must add the label. | Public repos accepting external issues. |
+
+### Input Sanitization
+
+- Issue titles and bodies are **never interpolated in shell commands**. The sync scripts use Node `execFile` with array arguments (no shell).
+- Workflow files pass event data via `env:` blocks, never via `${{ }}` in `run:` blocks (prevents GitHub Actions injection).
+- Only title, URL, mapped type, and priority are stored in Beads -- raw issue body is not committed.
+
+### SHA-Pinned Actions
+
+All third-party actions in the workflow files are pinned to full commit SHAs, not tags. This prevents supply-chain attacks via tag mutation.
+
+```yaml
+# Good: SHA-pinned
+- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+
+# Bad: tag-only (never used)
+- uses: actions/checkout@v4
+```
+
+---
+
+## Opt-Out
+
+Two ways to prevent an issue from syncing:
+
+1. **Label**: Add `skip-beads-sync` to the GitHub issue. The workflow checks labels before processing.
+2. **Body keyword**: Include `no-beads` anywhere in the issue body. Useful for quick one-off exclusions.
+
+Both are checked at the `issues.opened` trigger. If added after creation, they prevent close-sync but not the already-created Beads issue.
+
+---
+
+## Troubleshooting
+
+### Sync not triggering
+
+- **Check workflow is enabled**: Go to Actions tab in GitHub, verify `github-to-beads` workflow exists and is active.
+- **Check branch**: Workflows must exist on the default branch (usually `main` or `master`).
+- **Check permissions**: The workflow needs `contents: write` and `issues: write` permissions.
+
+### Duplicate Beads issues
+
+- The workflow checks for an existing `<!-- beads-sync:N -->` bot comment before creating. If the comment was deleted, a duplicate may be created.
+- Fix: Check `.github/beads-mapping.json` for the existing mapping and manually remove the duplicate Beads issue with `bd delete`.
+
+### Loop detection firing incorrectly
+
+- If legitimate commits starting with `chore(beads):` are being skipped by the Phase 2 workflow, rename the commit prefix in the workflow file.
+- The bot-actor check uses `github.actor` -- ensure your CI bot user matches the expected name.
+
+### Mapping file conflicts
+
+- If two issues are created simultaneously, the `git push` for the second may fail due to a stale mapping file.
+- The workflow retries with `git pull --rebase` up to 3 times. If it still fails, the workflow run will show as failed -- re-run it manually.
+
+### `bd` command not found in CI
+
+- The workflow installs Beads fresh each run: `bun add -g @beads/bd`.
+- If this fails, check that the workflow uses a runner with Node/Bun available.
+
+---
+
+## Fork Behavior
+
+Sync does **not** work in forks. The `GITHUB_TOKEN` provided to forked repo workflows is scoped to the fork and cannot write to the upstream repo's `.beads/` directory or post comments on upstream issues.
+
+When a fork PR uses `Closes #N`, GitHub closes the issue on the **upstream** repo on merge. This triggers the upstream's `issues.closed` workflow, which handles the Beads close normally.
+
+---
+
+## GitHub Projects Integration
+
+This plugin creates well-labeled GitHub issues but does **not** manage GitHub Projects boards. Use GitHub's built-in automation instead:
+
+### Setting Up Auto-Add to Project
+
+1. Go to your GitHub Project (Projects tab on your profile or org)
+2. Click the `...` menu, then **Workflows**
+3. Enable **"Auto-add to project"**
+4. Set the filter, for example: `is:issue is:open label:bug,enhancement`
+5. All matching issues (including those created by the sync) will auto-appear on your board
+
+### Recommended Project Views
+
+- **Board view**: Columns for `Open`, `In Progress`, `Done` -- map to Beads statuses
+- **Table view**: Add `Labels`, `Assignees`, `Priority` fields for triage
+- **Filter by label**: Use the labels mapped in your config to create focused views
+
+This approach is more flexible than automating board placement -- you control the filters and views entirely within GitHub's UI.
+
+---
+
+## Related Documentation
+
+- [Design doc](plans/2026-03-21-github-beads-sync-design.md) -- full design decisions, OWASP analysis, and edge cases
+- [Toolchain reference](TOOLCHAIN.md) -- Beads CLI commands, installation, and troubleshooting

package/docs/ENHANCED_ONBOARDING.md

@@ -180,12 +180,12 @@ bunx forge setup --type=feature
 
 **Critical Workflow (9 stages):**
 ```
-/status → /research → /plan → /dev → /validate → /ship → /review → /merge → /verify
+/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
 ```
 
 **Standard Workflow (6 stages):**
 ```
-/status → /plan → /dev → /validate → /ship → /merge
+/status → /plan → /dev → /validate → /ship → /premerge
 ```
 
 #### 2. Fix
@@ -208,7 +208,7 @@ bunx forge setup --type=fix
 
 **Simple Workflow (4 stages):**
 ```
-/dev → /validate → /ship → /merge
+/dev → /validate → /ship → /premerge
 ```
 
 #### 3. Refactor
@@ -221,7 +221,7 @@ bunx forge setup --type=refactor
 
 **Workflow (5 stages):**
 ```
-/plan → /dev → /validate → /ship → /merge
+/plan → /dev → /validate → /ship → /premerge
 ```
 
 - Strict TDD to preserve behavior
@@ -237,7 +237,7 @@ bunx forge setup --type=chore
 
 **Workflow (3 stages):**
 ```
-/verify → /ship → /merge
+/verify → /ship → /premerge
 ```
 
 - Minimal workflow for maintenance tasks
@@ -333,10 +333,10 @@ git checkout -b feat/user-authentication
 bunx forge setup --type=critical
 
 # Auto-escalates to Critical profile:
-# - 9-stage workflow
+# - 7-stage workflow
 # - Research required
 # - OWASP analysis
-# - OpenSpec for strategic changes
+# - Design docs for strategic changes
 ```
 
 ### Scenario 4: Production Hotfix
@@ -582,7 +582,7 @@ Share project knowledge with team.
 ## Related Documentation
 
 - [Main README](../README.md) - Overview and quick start
-- [Workflow Guide](WORKFLOW.md) - Complete 9-stage workflow
+- [Workflow Guide](../AGENTS.md) - Complete 7-stage workflow
 - [Setup Guide](SETUP.md) - Agent-specific setup
 - [Agent Install Prompt](AGENT_INSTALL_PROMPT.md) - AI-assisted setup
 

package/docs/EXAMPLES.md

@@ -70,7 +70,7 @@ router.get('/health', (req, res) => {
 git commit -m "feat: add health check endpoint"
 
 # ═══════════════════════════════════════════════════════════
-# STAGE 5: CHECK
+# STAGE 5: VALIDATE
 # ═══════════════════════════════════════════════════════════
 /validate
 
@@ -174,7 +174,7 @@ git commit -m "fix: prevent SQL injection in search endpoint
 OWASP A03:2021 Injection"
 
 # ═══════════════════════════════════════════════════════════
-# STAGE 5: CHECK
+# STAGE 5: VALIDATE
 # ═══════════════════════════════════════════════════════════
 /validate
 
@@ -294,7 +294,7 @@ git commit -m "refactor: extract login to AuthService"
 # 5-6 commits total
 
 # ═══════════════════════════════════════════════════════════
-# STAGE 5: CHECK
+# STAGE 5: VALIDATE
 # ═══════════════════════════════════════════════════════════
 /validate
 
@@ -475,7 +475,7 @@ bd sync
 
 📚 **New to Forge?** → [QUICKSTART.md](../QUICKSTART.md)
 
-📖 **Learn workflow** → [WORKFLOW.md](WORKFLOW.md)
+📖 **Learn workflow** → [AGENTS.md](../AGENTS.md)
 
 🛠️ **Setup tools** → [SETUP.md](SETUP.md)
 

package/docs/GREPTILE_SETUP.md

@@ -372,7 +372,7 @@ A: Yes, via `.greptile/config.yml` configuration file.
 - **Greptile Documentation**: https://docs.greptile.com
 - **GitHub App Settings**: https://github.com/settings/installations
 - **Branch Protection Guide**: [../.github/BRANCH_PROTECTION_GUIDE.md](../.github/BRANCH_PROTECTION_GUIDE.md)
-- **Your PR #13** (example): https://github.com/harshanandak/forge/pull/13
+- **Your PRs**: Check the [pull requests page](https://github.com/harshanandak/forge/pulls) for examples
 
 ---
 

package/docs/MANUAL_REVIEW_GUIDE.md

@@ -23,7 +23,7 @@ Manual review remains essential even with AI-powered tools like Greptile and Cod
 This guide integrates with the Forge 9-Stage TDD Workflow:
 
 ```
-/status → /research → /plan → /dev → /validate → /ship → /review → /merge → /verify
+/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
                                                            ↑
                                                   You are here
 ```

package/docs/ROADMAP.md

@@ -3,8 +3,8 @@
 **Comprehensive implementation plan for transforming Forge into a fully automated, orchestrated workflow system.**
 
 **Plan Created**: 2026-02-10
-**Status**: Phase 2 complete. PR5/PR6 research done, ready for planning.
-**Timeline**: 3-4 weeks total
+**Status**: Phase 2 complete. PRs 0-6 merged, PR7-PR8 pending.
+**Timeline**: Originally 3-4 weeks; Phases 0-2 complete as of March 2026.
 **Strategy**: Quick wins first → Build testing foundation → Add automation → Enable extensibility
 
 ---
@@ -87,8 +87,8 @@ PR0 (Simplification) → PR1 (Fixes) → PR2 (Security) → PR3 (Test Infra)
 | PR5 | PR4 | PR5.5 | ✅ MERGED (2026-02-20, PR #40) |
 | PR5.5 | PR5 | PR6 | ✅ MERGED (2026-02-23, PR #43) |
 | PR6 | PR5.5 | PR7 | ✅ MERGED (2026-02-21, PR #41) |
-| PR7 | PR6 | PR8 | Blocked |
-| PR8 | PR7 | None | Blocked |
+| PR7 | PR6 | PR8 | Planned |
+| PR8 | PR7 | None | Planned |
 
 ---
 
@@ -300,7 +300,7 @@ All PRs tracked in Beads with proper dependencies:
 Each PR follows the Forge workflow:
 
 ```
-/status → /research → /plan → /dev → /validate → /ship → /review → /merge → /verify
+/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
 ```
 
 **Current branch**: `master` (ready for next feature branch)
@@ -349,7 +349,7 @@ Each PR is self-contained and can be rolled back independently:
 
 - **Master Plan**: `.claude/plans/*.md`
 - **Beads Issues**: `bd list` or `bd show <issue-id>`
-- **Workflow Guide**: [WORKFLOW.md](./WORKFLOW.md)
+- **Workflow Guide**: [AGENTS.md](../AGENTS.md)
 - **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)
 
 ---

package/docs/SETUP.md

@@ -533,7 +533,6 @@ your-project/
 │   └── skills/forge-workflow/
 │
 ├── docs/
-│   ├── WORKFLOW.md              # Complete guide
 │   ├── TOOLCHAIN.md             # Tool reference
 │   ├── SETUP.md                 # This file
 │   ├── EXAMPLES.md              # Real examples
@@ -621,7 +620,7 @@ curl -s -X POST "https://api.parallel.ai/v1beta/search" \
 
 ✅ Setup complete? Try your [first feature](../QUICKSTART.md)
 
-📖 Learn the workflow in [WORKFLOW.md](WORKFLOW.md)
+📖 Learn the workflow in [AGENTS.md](../AGENTS.md)
 
 🛠️ Explore toolchain in [TOOLCHAIN.md](TOOLCHAIN.md)