@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khoa Vu Dang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# DoFlow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DoFlow is a configuration layer for AI coding tools. It gives Claude Code, Codex, Gemini /
+Antigravity, OpenCode, Pi, GitHub Copilot CLI, and Kiro a shared set of engineering rules, reusable
+workflows, and safer defaults — projected from one source, so the eight never drift apart.
+
+```mermaid
+flowchart LR
+    R[One DoFlow source] --> C[Claude Code]
+    R --> X[Codex]
+    R --> G[Gemini CLI]
+    R --> O[OpenCode]
+    R --> P[Pi]
+    R --> CP[Copilot CLI]
+    R --> K[Kiro]
+    R --> A[Antigravity CLI]
+    C --> H[Hooks + MCP + skills]
+    X --> S[AGENTS.md + skills]
+    G --> GM[GEMINI.md + skills]
+    A --> AG[AGENTS.md + .agents tree]
+    O --> S
+    P --> S
+    CP --> CI[copilot-instructions.md + skills]
+    K --> ST[Steering + skills]
+```
+
+## What it provides
+
+| Need | DoFlow component |
+|---|---|
+| Repeatable delivery work | 13 skills, including `/do-brainstorm`, `/do-plan`, `/do-test`, and `/do-code-review` |
+| Specialist review | 5 agents — `spec-analyst`, `system-architect`, `core-implementer`, `quality-guardian`, `research-writer` |
+| Safer automation | Claude hooks block destructive commands and unfinished implementation stubs |
+| Shared standards | Rules for safety, workflow, quality, and clarification across supported tools |
+| Session continuity | Claude and Codex hooks capture lightweight Git context and compact-session summaries and deliver them on a session's first prompt |
+
+## Start here
+
+1. **New to DoFlow?** Follow the [Quickstart](docs/quickstart.md).
+2. **Need installation, updates, or rollback?** Use the [Setup guide](docs/setup.md).
+3. **Want to understand the moving parts?** Read the visual [Overview](docs/overview.md).
+4. **Ready to work?** Pick a task pattern from the [Guide](docs/guide.md).
+5. **Looking up a command or capability?** Open the [Reference](docs/reference.md).
+
+## Install with the CLI
+
+Use the maintained installer when you want one source deployed to one or more tools. Nothing to
+clone — run it straight from npm:
+
+```bash
+# Inspect the plan first, then install globally.
+npx @khoavu882/doflow install --dry-run -g
+npx @khoavu882/doflow install -g --target claude,codex
+```
+
+To work on DoFlow itself, or to pin an installation to a checkout you control, link the repo
+instead — `doflow` then resolves to your working tree:
+
+```bash
+git clone git@github.com:khoavu882/do-flow.git ~/do-flow
+cd ~/do-flow
+npm link
+doflow install --dry-run -g
+```
+
+The package is published under the `@khoavu882` scope; the unscoped `doflow` name on npm belongs
+to an unrelated project.
+
+`doflow install` creates a backup before changing configuration. The complete command reference,
+including project-scoped installation and rollback, is in [Setup](docs/setup.md).
+
+## External tools
+
+DoFlow can inspect or manage the supported RTK and Graphify command-line tools on macOS and Linux:
+
+```bash
+doflow tools --tool rtk,graphify --action status
+doflow tools --tool graphify --action install --dry-run --json
+```
+
+`install`, `update`, and `uninstall` display and require confirmation for every command; `--force`
+is intentionally rejected. Graphify uses `uv` and DoFlow explains a missing `uv` prerequisite
+without installing it. RTK update is reported as skipped because no verified upstream update command
+is registered.
+
+## A typical feature flow
+
+```mermaid
+flowchart LR
+    B[Brainstorm] --> D[Design]
+    D --> P[Plan]
+    P --> E[Execute]
+    E --> T[Test]
+    T --> R[Review]
+```
+
+```text
+/do-brainstorm "add a customer export"
+/do-design
+/do-plan
+/do-execute-plan --scope next
+/do-test
+/do-code-review
+```
+
+Use `/do-flow "add a customer export"` to run the same sequence with its approval gates.
+
+## Tool support
+
+| Tool | Installed capabilities |
+|---|---|
+| Claude Code | Full integration: skills, agents, hooks, MCP registration, session context, and rules |
+| Codex | `AGENTS.md`, skills at `.agents/skills/`, scripts, templates, rules, agents, hooks, and references |
+| Gemini CLI | `GEMINI.md`, rules, agents, modes, skills, hooks, and references |
+| Antigravity CLI (`agy`) | Managed `AGENTS.md` section (project), skills at `.agents/skills/`, shared agents, workspace rules at `.agents/rules/`, the spec-driven chain workflow shim, the pre-implementation-gate hook (`.agents/hooks.json`), and MCP in `.agents/mcp_config.json` / `~/.gemini/config/mcp_config.json` |
+| OpenCode | `AGENTS.md`, skills discovered at `.opencode/skills/` (project) or `~/.config/opencode/skills/` (global), and `opencode.json` configuration |
+| Pi Coding Agent | `AGENTS.md`, skills discovered at `.pi/skills/` (project) or `~/.pi/agent/skills/` (global), and MCP servers in `.pi/mcp.json` (project) or `~/.pi/agent/mcp.json` (global) |
+| GitHub Copilot CLI | `.github/copilot-instructions.md` (project scope only), skills at `.agents/skills/`, agents at `.github/agents/`, and MCP registered in `.mcp.json` |
+| Kiro | Steering files under `.kiro/steering/`, skills at `.kiro/skills/`, agents at `.kiro/agents/`, hooks at `.kiro/hooks/`, and MCP registered in `.kiro/settings/mcp.json` |
+
+Codex hooks are installed as `hooks.json` but require review/trust in Codex before they run.
+Gemini hooks merge into a `hooks` key inside `settings.json` (never a full-file replace) and are
+similarly subject to Gemini's own hook trust/review gating. Kiro's hooks are not in Kiro v3's
+untrusted-workspace exclusion list; an untrusted workspace asks before every shell command, and
+whether that covers hook commands is undocumented. Copilot CLI documents hooks, settings, and a
+plugin marketplace upstream; DoFlow still installs none of those there. OpenCode and Pi
+standard-adopt `AGENTS.md` for seamless zero-drift rule projection. See `docs/capability-map.md`
+and the [installation matrix](docs/setup.md#what-gets-installed) for the exact mapping.
+
+## Contributing
+
+The repository layout and deployment model are documented in the [Architecture guide](docs/architecture.md).
+Run `npm test` and the shell suites described there before submitting changes.

package/bin/doflow.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+// doflow — DoFlow config installer CLI. Argument parsing, the installer command table and every
+// command handler live in src/cli/ (see docs/architecture.md); this file is only the forwarder
+// so the `doflow` binary path and the doflow-run dispatcher seam
+// (core/shared/scripts/doflow/bin/doflow-run, which execs `node <repoRoot>/bin/doflow.js`)
+// keep resolving to this exact location.
+// Refuse clearly on a Node that cannot strip types: src/ is TypeScript, and without stripping
+// loading a .ts module dies with a SyntaxError on the first annotation. Stripping is on by
+// default from Node 22.18.0 / 23.6.0 and off under --no-experimental-strip-types; the range stops at
+// 24.3.0 because 23.6 to 24.2 print an ExperimentalWarning on every .ts load. This file stays
+// plain JavaScript so it can say so. Exit 2 is the doflow-run usage/resolution-error code.
+if (!process.features || !process.features.typescript) {
+  process.stderr.write(`doflow: Node ${process.versions.node} cannot strip TypeScript types; doflow needs Node ^22.18.0 || >=24.3.0 with type-stripping enabled (it is off under --no-experimental-strip-types, including via NODE_OPTIONS).\n`);
+  process.exit(2);
+}
+// Enable Node's module compile cache before any ../src require. Type stripping makes the first load
+// of each .ts module cost a transform; the cache turns that into a one-time cost per Node version
+// and file content. Called without options so an explicit NODE_COMPILE_CACHE directory is honoured
+// and NODE_DISABLE_COMPILE_CACHE still disables it. Best-effort: where the API is missing (older
+// Node) or throws, the CLI runs at today's speed.
+const nodeModule = require('node:module');
+if (typeof nodeModule.enableCompileCache === 'function') {
+  try { nodeModule.enableCompileCache(); } catch { /* best-effort */ }
+}
+// Record an error that escapes everything, including one thrown while the CLI loads (a half-updated
+// install), before it is loaded (IC-016). The monitor only observes: Node's own crash output and
+// exit status are unchanged, and a monitor that threw would change that status to 7, hence the
+// try/catch around both the registration and the body. If the writer cannot load, nothing is
+// registered and the CLI runs as it always has. `cli` stays null until the CLI has loaded, so an
+// error thrown while it loads is recorded under the command name `unknown`.
+let cli = null;
+try {
+  const { captureError } = require('../src/runtime/failure/capture.ts');
+  process.on('uncaughtExceptionMonitor', (error) => {
+    try {
+      const argv = process.argv.slice(2);
+      const command = cli ? cli.commandName(argv.find((a) => !a.startsWith('-'))) : 'unknown';
+      captureError(error, { command, exit: 1, uncaught: true });
+    } catch { /* best-effort */ }
+  });
+} catch { /* best-effort */ }
+cli = require('../src/cli/index.ts');
+cli.main(process.argv.slice(2));

package/core/.antigravity-plugin/hooks.json

@@ -0,0 +1,39 @@
+{
+  "description": "DoFlow lifecycle hooks for Google Antigravity (IDE & CLI). Uses stdin/stdout JSON protocol for real-time gating.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "bash \"$DOFLOW_PROJECT_DIR/.gemini/hooks/session-start.sh\""
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "^(run_command|replace_file_content|write_to_file|multi_replace_file_content)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$DOFLOW_PROJECT_DIR/.doflow/scripts/stream-hook-runner.js\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(replace_file_content|write_to_file|multi_replace_file_content)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$DOFLOW_PROJECT_DIR/.gemini/hooks/post-edit-lint.sh\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "bash \"$DOFLOW_PROJECT_DIR/.gemini/hooks/stop-check.sh\""
+      }
+    ]
+  }
+}

package/core/.antigravity-plugin/mcp_config.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    }
+  }
+}

package/core/.antigravity-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "doflow",
+  "version": "1.0.0",
+  "description": "Spec-driven engineering workflow engine, quality gates, and specialist agent personas for Google Antigravity and Gemini.",
+  "author": {
+    "name": "DoFlow",
+    "url": "https://github.com/khoavu882/do-flow"
+  },
+  "homepage": "https://github.com/khoavu882/do-flow",
+  "repository": "https://github.com/khoavu882/do-flow",
+  "license": "MIT",
+  "keywords": [
+    "antigravity",
+    "gemini",
+    "engineering",
+    "workflows",
+    "quality-gates",
+    "spec-driven"
+  ],
+  "skills": [
+    "../../core/shared/skills/"
+  ],
+  "rules": [
+    "../../core/shared/guidance/rules/"
+  ],
+  "agents": [
+    "../../core/shared/agent-specs/"
+  ],
+  "hooks": "./hooks.json",
+  "mcp": "./mcp_config.json"
+}

package/core/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "doflow",
+  "description": "Engineering workflows, quality gates, and specialist guidance for Claude Code.",
+  "owner": {
+    "name": "DoFlow"
+  },
+  "plugins": [
+    {
+      "name": "doflow",
+      "description": "Reusable engineering workflows, quality gates, and specialist guidance for Claude Code.",
+      "author": {
+        "name": "DoFlow"
+      },
+      "category": "development",
+      "source": ".",
+      "homepage": "https://github.com/khoavu882/do-flow"
+    }
+  ]
+}

package/core/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "doflow",
+  "version": "2.0.0-beta.3",
+  "description": "Reusable engineering workflows, quality gates, and specialist guidance for Claude Code.",
+  "author": {
+    "name": "DoFlow"
+  },
+  "license": "MIT",
+  "keywords": [
+    "engineering",
+    "workflows",
+    "quality",
+    "claude-code"
+  ],
+  "skills": [
+    "./shared/skills/"
+  ],
+  "agents": [
+    "./shared/agent-specs/"
+  ]
+}

package/core/.codex-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "doflow",
+  "interface": {
+    "displayName": "DoFlow"
+  },
+  "plugins": [
+    {
+      "name": "doflow",
+      "source": {
+        "source": "local",
+        "path": "../../core"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/core/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "doflow",
+  "version": "2.0.0-beta.3",
+  "description": "Reusable engineering workflows, quality gates, and specialist guidance for Codex.",
+  "author": {
+    "name": "DoFlow",
+    "url": "https://github.com/khoavu882/do-flow"
+  },
+  "homepage": "https://github.com/khoavu882/do-flow",
+  "repository": "https://github.com/khoavu882/do-flow",
+  "license": "MIT",
+  "keywords": [
+    "engineering",
+    "workflows",
+    "quality",
+    "codex"
+  ],
+  "skills": "./shared/skills/",
+  "interface": {
+    "displayName": "DoFlow",
+    "shortDescription": "Engineering workflows and quality gates for Codex.",
+    "longDescription": "Reusable skills for implementation, review, testing, research, and disciplined engineering workflows.",
+    "developerName": "DoFlow",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Use DoFlow to review this change.",
+      "Use DoFlow to implement this feature safely.",
+      "Use DoFlow to create a focused test plan."
+    ]
+  }
+}

package/core/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "doflow",
+  "version": "2.0.0-beta.3",
+  "description": "Reusable engineering workflows, quality gates, and specialist guidance for GitHub Copilot CLI.",
+  "author": {
+    "name": "DoFlow",
+    "url": "https://github.com/khoavu882/do-flow"
+  },
+  "homepage": "https://github.com/khoavu882/do-flow",
+  "repository": "https://github.com/khoavu882/do-flow",
+  "license": "MIT",
+  "keywords": [
+    "engineering",
+    "workflows",
+    "quality",
+    "copilot"
+  ],
+  "skills": "./shared/skills/"
+}

package/core/harnesses/antigravity/hooks/pre-implementation-gate.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Antigravity front door: delegates the pre-implementation-gate decision to the
+# Canonical Policy Library via the Cross-Harness Hook Runner (design.md C2),
+# which owns Antigravity's native JSON stdin/stdout translation
+# (adapters/antigravity.js) — this file no longer implements the gate logic or
+# the translation itself, both of which moved to the shared runtime.
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-antigravity}"
+exec node "$(dirname "$0")/../../.doflow/shared/hooks/stream-hook-runner.js" PreToolUse

package/core/harnesses/antigravity/hooks/stop-check.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Antigravity front door: delegates the stop-check decision to the Canonical
+# Policy Library via the Cross-Harness Hook Runner (design.md C2), which owns
+# Antigravity's native JSON stdin/stdout translation (adapters/antigravity.js,
+# including its fail-open "silence lets the session end" Stop contract) — this
+# file no longer implements the check or the translation itself, both of which
+# moved to the shared runtime.
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-antigravity}"
+exec node "$(dirname "$0")/../../.doflow/shared/hooks/stream-hook-runner.js" Stop