forge-workflow 0.0.10 → 0.1.0-beta.3

package/docs/forge/VALIDATION.md

@@ -0,0 +1,82 @@
+# Validation Reference
+
+Forge validation is evidence, not a slogan. Record the command, result, and failure text when validation fails.
+
+## Project Validation
+
+In this repository:
+
+```bash
+bun run check
+```
+
+`bun run check` runs `scripts/validate.js` in this order:
+
+1. `bun run typecheck`
+2. `bun run lint`
+3. `bun audit`
+4. `node scripts/test.js --validate`
+
+Security audit behavior distinguishes blocking high/critical vulnerabilities from lower-severity warnings.
+
+## Supporting Commands
+
+```bash
+bun run typecheck
+bun run lint
+bun test --timeout 15000
+bun run validate:yaml
+npm pack --dry-run
+```
+
+Use `npm pack --dry-run` for package contents and release-readiness checks. It does not publish.
+
+## Agent Stage Validation
+
+`/validate` is an agent workflow stage. It may include rebase/freshness checks, local validation, manual security review, and Beads context updates according to the installed stage instructions.
+
+Do not confuse:
+
+- `/validate` - agent stage workflow
+- `forge-preflight` - prerequisite checker
+- `bun run check` - repository validation script
+
+## Work Artifact Paths
+
+Current planning and validation evidence should point to:
+
+```text
+docs/work/YYYY-MM-DD-<slug>/
+```
+
+Legacy `docs/research/` or `docs/plans/` examples are historical unless a specific tool documents a compatibility fallback.
+
+## Failure Recovery
+
+Fix failures in order:
+
+1. Typecheck
+2. Lint
+3. Security audit
+4. Tests
+5. Packaging
+
+For each failure:
+
+1. Reproduce with the exact command.
+2. Read the first real error.
+3. Fix the root cause.
+4. Rerun the full validation command.
+
+Do not proceed to ship with "should pass" or stale output.
+
+## Documentation Changes
+
+For docs-only changes, still run:
+
+```bash
+bun run check
+npm pack --dry-run
+```
+
+Run a Markdown link check when available. If adding docs tooling would broaden the PR, file follow-up work instead.

package/docs/{AGENT_INSTALL_PROMPT.md → guides/AGENT_INSTALL_PROMPT.md}

@@ -20,13 +20,13 @@ First, determine which AI agent you are by checking for these directories:
 
 ```bash
 # Check for agent-specific directories
-ls -la | grep -E "\.claude|\.cursor|\.cline"
+ls -la | grep -E "\.claude|\.codex|\.cursor"
 ```
 
 **Agent Detection:**
 - `.claude/` exists → You are **Claude Code**
+- `.codex/` exists → You are **Codex**
 - `.cursor/` exists → You are **Cursor**
-- `.cline/` exists → You are **Cline**
 - None exist → Generic agent
 
 Store this for later: `DETECTED_AGENT=<name>`
@@ -328,8 +328,8 @@ EOF
 
 **This prompt is designed to work with:**
 - Claude Code (via CLI)
+- Codex (via CLI)
 - Cursor (via chat)
-- Cline (via VSCode extension)
 - Any AI coding assistant with file system access
 
 ---

package/docs/guides/BEADS_GITHUB_SYNC.md

@@ -0,0 +1,32 @@
+# Beads/GitHub Sync Deprecation
+
+Beads/GitHub workflow sync is deprecated. Forge no longer ships active `github-to-beads.yml` or `beads-to-github.yml` workflow templates, and `forge setup --sync` must not create new Beads/GitHub sync scaffolding.
+
+## Current Behavior
+
+- `.beads/` is local runtime/export state and is not committed.
+- `forge setup --sync` is retained only as a compatibility cleanup path and removes old generated Beads/GitHub sync files from existing installs when they are present.
+- Plain `forge setup` does not perform Beads/GitHub sync cleanup as a side effect.
+- `forge sync` may still run local Beads/Dolt sync operations while Beads compatibility remains, but it is not GitHub issue lifecycle sync.
+
+## Removed Generated Files
+
+The `forge setup --sync` compatibility cleanup removes the old generated files:
+
+```text
+.github/workflows/github-to-beads.yml
+.github/workflows/beads-to-github.yml
+.github/beads-mapping.json
+.github/beads-sync-config.json
+.github/scripts/beads-sync/*.mjs
+scripts/github-beads-sync.config.json
+scripts/github-beads-sync/*.mjs
+```
+
+Unrelated GitHub workflows are preserved.
+
+## Replacement Direction
+
+Future GitHub issue sync must use Forge Kernel/server authority. Local-only work is durable in local Kernel SQLite. Team or cross-machine issue state is serialized through server authority, then GitHub issues can be updated as a projection from that authority.
+
+Do not commit live `.beads/` files, create metadata-only PRs, or bypass protected branches to update issue tracker state.

package/docs/{ENHANCED_ONBOARDING.md → guides/ENHANCED_ONBOARDING.md}

@@ -1,11 +1,15 @@
 # Enhanced Onboarding Guide
 
+> **Historical — superseded by [Quickstart](../../QUICKSTART.md).** This guide predates the current onboarding flow and still references the old `/premerge` stage and some undocumented flags. Kept for historical reference only; do not follow it for a fresh install.
+
 Intelligent onboarding that adapts to your project and preserves existing content.
 
 ---
 
 ## Key Features
 
+> This guide describes the broader onboarding experience and workflow-profile ideas. For current first-run setup, start with [Quickstart](../../QUICKSTART.md). For the current workflow-template boundary, use [Workflow templates](WORKFLOW_TEMPLATES.md).
+
 ### Key Features
 
 1. **Intelligent File Merging** - Preserves your existing AGENTS.md content
@@ -35,7 +39,7 @@ bunx forge setup --merge=smart
 - Tech stack details
 
 **What gets updated:**
-- Workflow instructions (7-stage TDD process)
+- Workflow instructions (composable TDD process)
 - TDD principles
 - Git conventions
 
@@ -65,7 +69,7 @@ E-commerce platform for selling widgets.
 - 80% test coverage
 
 ## Workflow Configuration
-Use the 7-stage TDD workflow:
+Use the default TDD workflow template:
 1. /plan - Design intent, research, branch + worktree + task list
 2. /dev - Subagent-driven TDD per task
 ...
@@ -165,7 +169,7 @@ Forge adapts its workflow based on the type of work you're doing.
 
 ### Six Change Classifications
 
-#### 1. Critical (7 stages)
+#### 1. Critical (full default template)
 **Use for:** Security, auth, payments, breaking changes
 
 ```bash
@@ -178,11 +182,11 @@ bunx forge setup --type=critical
 /plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
 ```
 
-- Full 7-stage workflow with all gates
+- Full default Forge workflow template with all gates
 - OWASP analysis required
 - Design docs for strategic changes
 
-#### 2. Standard (6 stages)
+#### 2. Standard (6 stages plus `/status` utility)
 **Use for:** Normal features, enhancements
 
 ```bash
@@ -199,7 +203,7 @@ bunx forge setup --type=standard
 - Auto-escalates to **Critical** if keywords detected:
   - auth, security, payment, crypto, password, token, session, migration, breaking
 
-#### 3. Simple (3 stages)
+#### 3. Simple (4 stages)
 **Use for:** Bug fixes, small changes
 
 ```bash
@@ -209,7 +213,7 @@ bunx forge setup --type=simple
 
 **Workflow:**
 ```
-/dev -> /validate -> /ship
+/dev -> /validate -> /ship -> /premerge
 ```
 
 - Streamlined for quick fixes
@@ -232,7 +236,7 @@ bunx forge setup --type=hotfix
 - Skip planning and research
 - TDD to reproduce, then fix
 
-#### 5. Docs (2 stages)
+#### 5. Docs (3 stages)
 **Use for:** Documentation only
 
 ```bash
@@ -242,7 +246,7 @@ bunx forge setup --type=docs
 
 **Workflow:**
 ```
-/verify -> /ship
+/verify -> /ship -> /premerge
 ```
 
 - Minimal workflow for documentation changes
@@ -354,7 +358,7 @@ git checkout -b feat/user-authentication
 bunx forge setup --type=critical
 
 # Uses Critical profile:
-# - Full 7-stage workflow
+# - Full default Forge workflow template
 # - OWASP analysis required
 # - Design docs for strategic changes
 ```
@@ -593,8 +597,8 @@ Share project knowledge with team.
 
 ## Related Documentation
 
-- [Main README](../README.md) - Overview and quick start
-- [Workflow Guide](../AGENTS.md) - Complete 7-stage workflow
+- [Main README](../../README.md) - Overview and quick start
+- [Workflow Guide](../../AGENTS.md) - Complete default Forge workflow template
 - [Setup Guide](SETUP.md) - Agent-specific setup
 - [Agent Install Prompt](AGENT_INSTALL_PROMPT.md) - AI-assisted setup
 

package/docs/guides/GREPTILE_SETUP.md

@@ -0,0 +1,46 @@
+# Greptile Code Review Setup
+
+Greptile is an optional review integration. Do not assume it is installed, required by branch protection, or present on every Forge consumer repository. Verify the current repository's checks before documenting Greptile as a required gate.
+
+## Verify Current Status
+
+```bash
+gh pr checks <pr-number>
+gh api repos/<owner>/<repo>/branches/<branch>/protection
+```
+
+If Greptile appears on PRs and you want it to block merges, add the exact check name reported by GitHub to branch protection. Required check names are repository-specific.
+
+## How Greptile Fits Forge
+
+- Greptile can provide PR review comments through the GitHub App.
+- A repository may add a custom quality-gate workflow.
+- Forge review work should reply to and resolve actionable review threads.
+- The review adapter scaffold currently supports Greptile-shaped review adapters.
+
+## Setup Boundary
+
+Forge does not guarantee that Greptile is installed or enforced. Treat Greptile as repository configuration:
+
+1. Install/configure the Greptile GitHub App.
+2. Confirm it runs on a PR.
+3. Add required checks only after the check name is visible.
+4. Document the configured branch-protection rule in the repository.
+
+## Review Handling
+
+When the repo includes the helper script:
+
+```bash
+bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
+bash .claude/scripts/review-resolve.sh stats <pr-number>
+```
+
+Reply to each valid, invalid, conflicting, or out-of-scope thread before resolving it.
+
+## Known Limits
+
+- Greptile availability depends on GitHub App installation and repository access.
+- Branch protection may not include Greptile even when Greptile comments on PRs.
+- Required check names can change if workflows or integrations are renamed.
+

package/docs/guides/MANUAL_REVIEW_GUIDE.md

@@ -0,0 +1,58 @@
+# Manual Review Guide
+
+Manual review remains required even when AI review tools are configured.
+
+## Workflow Boundary
+
+`/review` is an agent workflow stage. It is not currently documented as a standalone `forge review` CLI command. Use GitHub, `gh`, adapter tools, and the installed agent review skill for PR review work.
+
+Default stage context:
+
+```text
+/plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+These are the 6 workflow stages. Pre-merge is not a stage or a `/premerge` command — it is a documentation-and-handoff gate embedded in `/ship` and `/review`.
+
+## Review Inputs
+
+Check all available inputs:
+
+- GitHub Actions and required checks
+- human review comments
+- Greptile or other review-bot comments, when configured
+- SonarCloud or code-scanning findings, when configured
+- local validation evidence from `bun run check`
+- design and task artifacts under `docs/work/YYYY-MM-DD-<slug>/`
+
+## Checklist
+
+- The PR description matches the diff.
+- The change stays inside scope.
+- User-facing commands are verified against current code.
+- Security-sensitive claims are backed by code, tests, or configured CI.
+- Tests or validation evidence match the risk of the change.
+- Documentation changes do not present future roadmap work as ready now.
+- Review threads are replied to and resolved where the platform supports it.
+
+## Greptile
+
+If Greptile is configured for the repository, use the repo's review-thread resolution script when available (it handles Greptile and any other review author):
+
+```bash
+bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
+```
+
+Then reply to each thread with the fix, rejection reason, or follow-up issue.
+
+## Final State
+
+Before calling review complete:
+
+```bash
+gh pr checks <pr-number>
+gh pr view <pr-number> --json reviews,comments,statusCheckRollup
+```
+
+All completed required checks should be passing, and unresolved comments should either be fixed or explicitly answered.
+

package/docs/guides/MIGRATION.md

@@ -0,0 +1,56 @@
+# Migration Guide
+
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.0.11 public framing.
+
+## What Changed
+
+Forge is now documented as a local runtime control plane for AI-assisted engineering. The TDD-first workflow is still the default template, but it is no longer the only public explanation of Forge.
+
+## From Stage-Only Docs
+
+Old docs often describe Forge as a fixed seven-, eight-, or nine-stage workflow. Replace that with:
+
+```text
+Default template: /plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+These are the 6 workflow stages. Pre-merge is not a stage or a `/premerge` command — it is a documentation-and-handoff gate embedded in `/ship` and `/review`. A composable `research` skill runs as a phase of `/plan` or standalone. Then add the boundary:
+
+```text
+These are agent workflow stages. Not every stage is a standalone forge CLI command.
+```
+
+## From `forge setup` Only
+
+Use both entry points correctly:
+
+- `forge init` creates the `.forge/` adoption skeleton.
+- `forge setup` installs agent instructions, skills, harness files, local Beads compatibility, and optional setup material.
+- `forge setup --sync` is deprecated and retained only to remove old generated Beads/GitHub sync scaffolding when present.
+
+## From Singular Agent Flags
+
+Replace stale examples that use the old singular agent flag form with:
+
+```bash
+forge setup --agents codex
+forge setup --agents claude,cursor
+```
+
+## Version Labels
+
+- `0.0.11` is the package version for this public docs/readiness release.
+- `0.0.10` is the previous published package version.
+- Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
+
+## Safe Upgrade Path
+
+1. Update docs and examples first.
+2. Run `bun run check`.
+3. Run `npm pack --dry-run`.
+4. Open a PR.
+5. After merge, refresh DeepWiki and verify generated pages against repository docs.
+
+## Rollback
+
+If migration creates confusion, revert the release PR or open a corrective docs PR. Do not publish a package version unless README, CHANGELOG, quickstart, support docs, and package metadata agree.

package/docs/guides/SETUP.md

@@ -0,0 +1,121 @@
+# Setup Guide
+
+This guide covers supported Forge adoption paths. Use [Quickstart](../../QUICKSTART.md) for the shortest path and [Support](SUPPORT.md) when setup fails.
+
+## Prerequisites
+
+- Git
+- Node.js and Bun
+- GitHub CLI if using PR or sync workflows
+- Optional: Beads (`bd`) as an opt-out issue backend (issue commands use the built-in kernel backend by default)
+
+## Install
+
+```bash
+bun add -D forge-workflow@beta
+```
+
+> The current release is a prerelease under the `beta` dist-tag — install with
+> `@beta`. A bare `forge-workflow` resolves to the older stable `latest`.
+
+The package exposes `forge`, `forge-workflow`, and `forge-preflight`.
+
+`install.sh` is a thin bootstrapper. It installs or invokes `forge-workflow` and delegates setup to the package; it is not a separate implementation of setup behavior.
+
+## Fresh Repository Runtime Skeleton
+
+Use `forge init` when you want only the local `.forge/` adoption skeleton:
+
+```bash
+bunx forge init --profile minimal --classification standard --harness codex --yes
+```
+
+Supported options:
+
+```text
+--profile minimal|standard|full
+--classification critical|standard|refactor
+--harness claude,cursor,codex
+--yes
+--force
+--dry-run
+```
+
+`forge init` creates `.forge/config.yaml`, `.forge/patch.md`, and `.forge/protected-paths.yaml`. It does not install agent instructions.
+
+## Agent Setup
+
+Use `forge setup` when you want agent-facing files:
+
+```bash
+bunx forge setup --agents codex --yes
+```
+
+Safe examples:
+
+```bash
+bunx forge setup --agents claude,cursor
+bunx forge setup --agents claude cursor
+bunx forge setup --all --quick
+bunx forge setup --path ./my-project --agents codex --dry-run
+bunx forge setup --merge smart --agents claude,cursor
+```
+
+Use `--agents`, not `--agent`.
+
+## Agent Notes
+
+Forge currently supports Claude Code, Codex, and Cursor. Hermes support is planned.
+
+- Claude Code: installs `.claude/commands`, rules, and skills when selected.
+- Cursor: installs Cursor rules and links back to `AGENTS.md`.
+- Codex: uses `AGENTS.md` and may use Codex skills when installed.
+
+Exact generated files depend on selected agents and existing repository files. Use `--dry-run` before applying setup to a mature repo.
+
+## Issue Backend
+
+Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend by default. No install or initialization is required — a fresh clone can track issues immediately.
+
+## Beads (Opt-Out Backend)
+
+Beads (`bd`) is an optional opt-out backend for teams that prefer Dolt-backed sync internals. Select it (precedence, highest first) with `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`; only then is `bd` required. Prefer the current Beads installer documented by Beads itself and this repo's toolchain docs. On Windows, avoid stale global install examples if they hit EPERM or shim issues; use the PowerShell installer path described in [Toolchain](../reference/TOOLCHAIN.md).
+
+When Beads is selected, health checks:
+
+```bash
+bd doctor
+bd dolt status
+forge sync
+```
+
+If a feature worktree reports `database "forge" not found on Dolt server`, diagnose in the root checkout before changing issue state. This applies only to the Beads backend.
+
+## Deprecated GitHub Sync Cleanup
+
+To remove old generated GitHub/Beads sync files from an existing install:
+
+```bash
+bunx forge setup --sync
+```
+
+`forge setup --sync` is deprecated. It now removes old generated Beads/GitHub sync files instead of creating new sync workflows. Future GitHub issue sync belongs to Forge Kernel/server authority, not Beads runtime files or metadata commits.
+
+## Validate Setup
+
+```bash
+bunx forge status --json
+bunx forge board --json
+bun run check
+```
+
+## Troubleshooting
+
+Use [Support and troubleshooting](SUPPORT.md) for:
+
+- Beads/Dolt database errors
+- Windows locked files
+- protected-state blocks
+- branch-protection push failures
+- validation failures
+- DeepWiki refresh drift