forge-workflow 0.0.8 → 0.0.9

package/docs/BEADS_GITHUB_SYNC.md

@@ -3,10 +3,14 @@
 Automatic synchronization between GitHub Issues and Beads issue tracking.
 
 **GitHub Issues** = human/team/public interface.
-**Beads** = AI agent engine (`bd ready`, `bd close`).
+**Beads** = issue engine behind Forge (`forge ready`, `forge 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.
 
+For human and agent workflows, prefer the Forge wrapper commands (`forge ready`,
+`forge create`, `forge close`, `forge sync`). The workflow automation shown below
+still calls `bd` directly as an internal implementation detail.
+
 ---
 
 ## Architecture
@@ -48,7 +52,7 @@ sequenceDiagram
     participant WF as GitHub Actions
     participant GH as GitHub Issues
 
-    AI->>BD: bd close forge-abc
+    AI->>BD: forge close forge-abc
     BD->>Repo: Update issues.jsonl
     AI->>Repo: git push
     Repo->>WF: push trigger (paths: .beads/**)

package/docs/EXAMPLES.md

@@ -109,7 +109,7 @@ git commit -m "feat: add health check endpoint"
 /status
 
 # If Beads installed:
-bd create "SQL injection in search endpoint" \
+forge create "SQL injection in search endpoint" \
   --type bug \
   --priority 0 \
   --label "security,critical"
@@ -224,7 +224,7 @@ OWASP A03:2021 Injection"
 # ═══════════════════════════════════════════════════════════
 /status
 
-bd create "Extract auth logic to service" \
+forge create "Extract auth logic to service" \
   --type chore \
   --priority 2
 
@@ -337,35 +337,35 @@ Team of 3 developers:
 # PROJECT SETUP (Once per project)
 # ═══════════════════════════════════════════════════════════
 bd init --prefix SHOP
-bd sync  # Commit .beads/ to git
+forge sync  # Sync initial Beads state
 
 # ═══════════════════════════════════════════════════════════
 # ALICE: Payment Integration
 # ═══════════════════════════════════════════════════════════
 
 # Morning: Check what's available
-bd ready
+forge ready
 # Output:
 # SHOP-1: Payment integration (ready)
 # SHOP-3: Admin dashboard (ready)
 
 # Claim work
-bd update SHOP-1 --status in_progress
+forge claim SHOP-1
 /status
 /plan stripe-payment-integration
 /dev
 
 # Midday: Progress update
-bd comments SHOP-1 "Stripe SDK integrated, working on webhooks"
+bd comments add SHOP-1 "Stripe SDK integrated, working on webhooks"
 
 # Afternoon: Blocked on API keys
-bd update SHOP-1 --status blocked --comment "Need production Stripe API keys"
+forge update SHOP-1 --status blocked --comment "Need production Stripe API keys"
 
 # Create dependency
-bd create "Get Stripe API keys from DevOps" --type chore --priority 1
+forge create "Get Stripe API keys from DevOps" --type chore --priority 1
 bd dep add SHOP-1 SHOP-5  # SHOP-1 depends on SHOP-5
 
-bd sync  # Push to git
+forge sync  # Push Beads state
 
 # ═══════════════════════════════════════════════════════════
 # BOB: Email Notifications (Same Time)
@@ -373,24 +373,24 @@ bd sync  # Push to git
 
 # Morning: Pull latest, check work
 git pull
-bd sync  # Sync with Alice's updates
+forge sync  # Sync with Alice's updates
 
-bd ready
+forge ready
 # Output:
 # SHOP-3: Admin dashboard (ready)
 # SHOP-2: Email notifications (ready)
 
 # Claim different feature
-bd update SHOP-2 --status in_progress
+forge claim SHOP-2
 /plan email-notifications
 /dev
 
 # No conflicts with Alice (different files)
 
 # End of day: Complete
-bd close SHOP-2 --reason "Implemented with SendGrid"
+forge close SHOP-2 --reason "Implemented with SendGrid"
 /ship
-bd sync
+forge sync
 
 # ═══════════════════════════════════════════════════════════
 # CHARLIE: Admin Dashboard (Next Day)
@@ -398,17 +398,17 @@ bd sync
 
 # Morning: Check dependencies
 git pull
-bd sync
+forge sync
 
-bd show SHOP-3
+forge show SHOP-3
 # Output:
 # Status: ready
 # Depends on: (none)
 
-bd update SHOP-3 --status in_progress
+forge claim SHOP-3
 
 # Discovers overlap with Bob's work
-bd comments SHOP-3 "Need Bob's email service for user notifications"
+bd comments add SHOP-3 "Need Bob's email service for user notifications"
 bd dep add SHOP-3 SHOP-2  # SHOP-3 depends on SHOP-2
 
 # Bob's work already merged, so can proceed
@@ -428,7 +428,7 @@ bd blocked
 # SHOP-1: Payment integration (blocked by SHOP-5)
 
 # Find work with no blockers:
-bd ready
+forge ready
 
 # See full project status:
 bd stats
@@ -440,7 +440,7 @@ bd stats
 # Done: 4
 
 # Always sync at end of session:
-bd sync
+forge sync
 ```
 
 **Result**: Team can work in parallel, track dependencies, and avoid conflicts.
@@ -465,8 +465,8 @@ bd sync
 
 ### 4. Team Collaboration
 - Beads tracks dependencies
-- `bd ready` finds available work
-- `bd sync` at end of every session
+- `forge ready` finds available work
+- `forge sync` at end of every session
 - Comments keep teammates informed
 
 ---

package/docs/ROADMAP.md

@@ -291,8 +291,8 @@ All PRs tracked in Beads with proper dependencies:
 | PR8 | forge-dwm | Blocked | P3 | PR7 |
 | ~~Skills CLI~~ | ~~forge-mlm~~ | ~~Absorbed into PR5.5 + PR6 + PR8~~ | — | — |
 
-**View all issues**: `bd list`
-**View ready work**: `bd ready`
+**View all issues**: `forge list`
+**View ready work**: `forge ready`
 **View blocked issues**: `bd blocked`
 
 ### Git Workflow
@@ -348,7 +348,7 @@ Each PR is self-contained and can be rolled back independently:
 ## Resources
 
 - **Master Plan**: `docs/plans/*.md`
-- **Beads Issues**: `bd list` or `bd show <issue-id>`
+- **Beads Issues**: `forge list` or `forge show <issue-id>`
 - **Workflow Guide**: [AGENTS.md](../AGENTS.md)
 - **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)
 

package/docs/TOOLCHAIN.md

@@ -42,7 +42,7 @@ Complete reference for all tools integrated with the Forge workflow.
 - **Persists across sessions** - Issues survive context clearing, compaction, new chats
 - **Git-backed** - Version controlled, mergeable, team-shareable
 - **Dependency tracking** - Know what blocks what
-- **Ready detection** - `bd ready` finds unblocked work automatically
+- **Ready detection** - `forge ready` finds unblocked work automatically
 - **AI-optimized** - JSON output, semantic compaction, audit trails
 
 ### Installation
@@ -91,6 +91,11 @@ After `bd init`, creates `.beads/` directory:
 
 **Dual-database architecture**: JSONL for git versioning, SQLite for fast local queries. Background daemon keeps them in sync.
 
+For day-to-day issue workflows, prefer the Forge wrapper commands (`forge ready`,
+`forge create`, `forge update`, `forge close`, `forge sync`). Use `bd` directly
+for Beads capabilities Forge does not wrap yet, such as `bd init`, `bd comments`,
+`bd dep`, `bd blocked`, and `bd dolt *`.
+
 ### Complete Command Reference
 
 #### Initialization
@@ -106,36 +111,36 @@ bd init --prefix PROJ      # Custom issue prefix (PROJ-xxx)
 
 ```bash
 # Create issues
-bd create "Title"                           # Basic issue
-bd create "Title" --type feature            # With type (feature, bug, chore, etc.)
-bd create "Title" --priority 1              # With priority (0=critical, 4=backlog)
-bd create "Title" -p 0 -l "urgent,backend"  # P0 with labels
+forge create "Title"                           # Basic issue
+forge create "Title" --type feature            # With type (feature, bug, chore, etc.)
+forge create "Title" --priority 1              # With priority (0=critical, 4=backlog)
+forge create "Title" -p 0 -l "urgent,backend"  # P0 with labels
 
 # View issues
-bd show <id>                   # Detailed view with audit trail
-bd list                        # All issues
-bd list --status open          # Filter by status
-bd list --priority 1           # Filter by priority
-bd list --assignee bob         # Filter by assignee
-bd list --label bug            # Filter by label (AND logic)
-bd list --label-any bug,urgent # Filter by label (OR logic)
-bd list --type feature         # Filter by type
-bd list --title-contains "auth" # Search titles
-bd list --limit 10             # Limit results
+forge show <id>                   # Detailed view with audit trail
+forge list                        # All issues
+forge list --status open          # Filter by status
+forge list --priority 1           # Filter by priority
+forge list --assignee bob         # Filter by assignee
+forge list --label bug            # Filter by label (AND logic)
+forge list --label-any bug,urgent # Filter by label (OR logic)
+forge list --type feature         # Filter by type
+forge list --title-contains "auth" # Search titles
+forge list --limit 10             # Limit results
 
 # Update issues
-bd update <id> --status in_progress     # Change status
-bd update <id> --priority 2             # Change priority
-bd update <id> --assignee bob           # Assign
-bd update <id> --title "New title"      # Update title
-bd update <id> --description "..."      # Update description
-bd update <id> --notes "..."            # Add notes
-bd update <id> --label-add urgent       # Add label
+forge claim <id>                        # Claim work (sets in_progress)
+forge update <id> --priority 2          # Change priority
+forge update <id> --assignee bob        # Assign
+forge update <id> --title "New title"   # Update title
+forge update <id> --description "..."   # Update description
+forge update <id> --notes "..."         # Add notes
+forge update <id> --add-label urgent    # Add label
 
 # Complete issues
-bd close <id>                           # Close single issue
-bd close <id1> <id2> <id3>              # Close multiple (efficient)
-bd close <id> --reason "Completed auth" # Close with reason
+forge close <id>                           # Close single issue
+forge close <id1> <id2> <id3>              # Close multiple (efficient)
+forge close <id> --reason "Completed auth" # Close with reason
 bd delete <id>                          # Delete issue
 bd delete <id> --cascade                # Delete with dependents
 ```
@@ -144,8 +149,8 @@ bd delete <id> --cascade                # Delete with dependents
 
 ```bash
 # Find work
-bd ready                        # Issues with NO open blockers (start here!)
-bd ready --priority 1           # Filter ready work by priority
+forge ready                     # Issues with NO open blockers (start here!)
+forge ready --priority 1        # Filter ready work by priority
 bd blocked                      # Issues that ARE blocked
 
 # Dependencies
@@ -158,11 +163,11 @@ bd dep cycles                                  # Detect cycles
 
 # Comments
 bd comments <id>                # View comments
-bd comments <id> "Comment text" # Add comment
+bd comments add <id> "Comment text" # Add comment
 
 # Git sync
-bd sync                         # Export to JSONL, commit, push
-bd sync --status                # Check sync status
+forge sync                      # Pull + push Beads state through the Forge wrapper
+bd dolt status                  # Check Dolt sync/server status
 bd hooks install                # Install git hooks for auto-sync
 
 # Maintenance
@@ -203,18 +208,18 @@ bd admin compact --days 90      # Compact old closed issues
 
 ```bash
 # Start of session
-bd ready                    # What can I work on?
-bd show <id>                # Review the issue
-bd update <id> --status in_progress
+forge ready                 # What can I work on?
+forge show <id>             # Review the issue
+forge claim <id>
 
 # During work
-bd comments <id> "Progress update"
-bd update <id> --notes "Found edge case"
+bd comments add <id> "Progress update"
+forge update <id> --notes "Found edge case"
 
 # End of session
-bd close <id>               # If done, or:
-bd update <id> --status blocked --comment "Needs API response"
-bd sync                     # Always sync at end!
+forge close <id>            # If done, or:
+forge update <id> --status blocked --comment "Needs API response"
+forge sync                  # Always sync at end!
 ```
 
 ---
@@ -556,7 +561,10 @@ bun add -g @beads/bd
 irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 ```
 
-> **Why v0.49.x?** Earlier versions lack the `bd ready` dependency-aware query, `bd sync --status`, and the dual-database (JSONL + SQLite) architecture that Forge relies on.
+> **Why Forge + Beads?** Forge wraps the supported day-to-day issue workflow
+> (`forge ready`, `forge create`, `forge close`, `forge sync`) while Beads
+> remains the underlying store for initialization, dependencies, comments, and
+> Dolt-backed sync internals.
 
 ---
 
@@ -564,14 +572,14 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 | Stage | Tools Used |
 |-------|------------|
-| `/status` | `bd ready`, `bd list`, `git status` |
+| `/status` | `forge ready`, `forge list`, `git status` |
 | `/plan` (Phase 2) | Parallel AI, Context7, grep.app, codebase exploration |
-| `/plan` | `bd create`, `git checkout -b` |
-| `/dev` | Tests, code, `bd update`, `/tasks save` |
+| `/plan` | `forge create`, `git checkout -b` |
+| `/dev` | Tests, code, `forge update`, `/tasks save` |
 | `/validate` | Type check, lint, tests, SonarCloud |
-| `/ship` | `bd update --status done`, `gh pr create` |
+| `/ship` | `forge close`, `gh pr create` |
 | `/review` | `gh pr view`, Greptile, SonarCloud |
-| `/premerge` | `bd sync`, doc updates, hand off PR |
+| `/premerge` | `forge sync`, doc updates, hand off PR |
 | `/verify` | Documentation cross-check |
 
 ---
@@ -582,13 +590,13 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 ```bash
 bd init                     # Initialize
-bd ready                    # Find unblocked work
-bd create "Title"           # Create issue
-bd show <id>                # View details
-bd update <id> --status X   # Update status
+forge ready                 # Find unblocked work
+forge create "Title"        # Create issue
+forge show <id>             # View details
+forge update <id> --status X   # Update status
 bd dep add <a> <b>          # a depends on b
-bd close <id>               # Complete
-bd sync                     # Git sync
+forge close <id>            # Complete
+forge sync                  # Beads sync
 ```
 
 ### GitHub CLI
@@ -626,12 +634,12 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 **"database locked"**
 ```bash
-bd sync --force
+forge sync
 ```
 
 **Issues not showing after git pull**
 ```bash
-bd sync  # Re-imports from JSONL
+forge sync  # Re-syncs Beads state through the Forge wrapper
 ```
 
 ### GitHub CLI

package/lib/agents/codex.plugin.json

@@ -12,6 +12,9 @@
   "directories": {
     "skills": ".codex/skills"
   },
+  "installTargets": {
+    "skills": "$CODEX_HOME/skills"
+  },
   "setup": {
     "copyRules": false,
     "createSkill": true

package/lib/agents-config.js

@@ -220,16 +220,19 @@ Configuration: \`.mcp.json\` or agent-specific config files
 
 ## Issue Tracking
 
-Use **Beads** for persistent tracking across sessions:
+Use **Forge's Beads wrapper** for persistent tracking across sessions:
 
 \`\`\`bash
-bd create "Feature name"              # Create issue
-bd update <id> --status in_progress   # Claim work
-bd update <id> --comment "Progress"   # Add notes
-bd close <id>                          # Complete
-bd sync                                # Sync with git
+forge create "Feature name"              # Create issue
+forge claim <id>                         # Claim work
+forge update <id> --append-notes "Progress" # Add notes
+forge close <id>                         # Complete
+forge sync                               # Sync Beads state
 \`\`\`
 
+Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
+\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
+
 ## Git Workflow
 
 **Branch naming**:
@@ -480,16 +483,19 @@ Configure these MCP servers in \`.mcp.json\`:
 
 ## Issue Tracking with Beads
 
-Use **Beads** for persistent tracking across sessions:
+Use **Forge's Beads wrapper** for persistent tracking across sessions:
 
 \`\`\`bash
-bd create "Feature name"                  # Create issue
-bd update <id> --status in_progress       # Claim work
-bd update <id> --append-notes "Progress"  # Add notes
-bd close <id>                              # Complete
-bd sync                                    # Sync with git
+forge create "Feature name"                # Create issue
+forge claim <id>                           # Claim work
+forge update <id> --append-notes "Progress" # Add notes
+forge close <id>                           # Complete
+forge sync                                 # Sync Beads state
 \`\`\`
 
+Use \`bd\` directly only for capabilities Forge does not wrap yet, such as
+\`bd init\`, \`bd comments\`, \`bd dep\`, and \`bd dolt\`.
+
 ## Code Quality Standards
 
 ${meta.language === 'TypeScript' ? `

package/lib/codex-skills.js

@@ -1,4 +1,5 @@
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 
 function injectForgeAdapter(content, commandName) {
@@ -37,7 +38,6 @@ function listCodexSkillEntries(sourceRoot) {
 
       return {
         commandName,
-        dir: `.codex/skills/${commandName}/`,
         filename: 'SKILL.md',
         content: injectForgeAdapter(fs.readFileSync(sourceFile, 'utf8'), commandName),
       };
@@ -45,6 +45,59 @@ function listCodexSkillEntries(sourceRoot) {
     .filter(Boolean);
 }
 
+function resolveCodexHome(options = {}) {
+  const env = options.env || process.env;
+  const homeDir = options.homeDir || os.homedir();
+  const explicitHome = String(env.CODEX_HOME || '').trim();
+
+  if (explicitHome) {
+    return path.resolve(explicitHome);
+  }
+
+  return path.join(homeDir, '.codex');
+}
+
+function resolveCodexSkillsInstallDir(options = {}) {
+  return path.join(resolveCodexHome(options), 'skills');
+}
+
+function formatCodexSkillsInstallDir(options = {}) {
+  const installDir = resolveCodexSkillsInstallDir(options);
+  const homeDir = path.resolve(options.homeDir || os.homedir());
+  const explicitHome = String((options.env || process.env).CODEX_HOME || '').trim();
+  const normalizedInstallDir = installDir.replace(/\\/g, '/');
+
+  if (explicitHome) {
+    const explicitInstallDir = path.join(path.resolve(explicitHome), 'skills').replace(/\\/g, '/');
+    if (normalizedInstallDir === explicitInstallDir) {
+      return '$CODEX_HOME/skills';
+    }
+  }
+
+  const defaultInstallDir = path.join(homeDir, '.codex', 'skills').replace(/\\/g, '/');
+  if (normalizedInstallDir === defaultInstallDir) {
+    return '~/.codex/skills';
+  }
+
+  return normalizedInstallDir;
+}
+
+function buildCodexSkillInstallPlan(sourceRoot, options = {}) {
+  const installDir = resolveCodexSkillsInstallDir(options);
+  const displayRoot = formatCodexSkillsInstallDir(options);
+
+  return listCodexSkillEntries(sourceRoot).map((entry) => ({
+    ...entry,
+    absolutePath: path.join(installDir, entry.commandName, entry.filename),
+    displayPath: `${displayRoot}/${entry.commandName}/${entry.filename}`,
+    displayRoot,
+  }));
+}
+
 module.exports = {
+  buildCodexSkillInstallPlan,
+  formatCodexSkillsInstallDir,
   listCodexSkillEntries,
+  resolveCodexHome,
+  resolveCodexSkillsInstallDir,
 };

package/lib/commands/plan.js

@@ -254,8 +254,11 @@ function createBeadsIssue(featureName, researchPath, scope) {
 			getExecOptions()
 		);
 
-		// Extract issue ID from output (format: "Created issue: forge-xxx")
-		const match = /Created issue:\s*(forge-[a-z0-9]+)/i.exec(result) || /(forge-[a-z0-9]+)/.exec(result);
+		// Extract issue ID from output (format: "Created issue: forge-xxx" or "forge-xxx.N" for dotted sub-IDs).
+		// Character class is [a-z0-9] (not [a-zA-Z0-9]) because the /i flag makes A-Z redundant.
+		const createPattern = /Created issue:\s*(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
+		const fallbackPattern = /(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
+		const match = createPattern.exec(result) || fallbackPattern.exec(result);
 
 		if (!match) {
 			return {