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

package/core/shared/templates/doflow/requirement-template.md

@@ -0,0 +1,126 @@
+# Feature Requirement: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Branch:** `feat/[NNN-slug]` · **Maturity:** Draft
+**Created:** [DATE] · **Owner:** [OWNER] · **Ticket:** [PBI/ticket ID, or "none"]
+**Intent:** [agent-docs/intent/<name>.md, or "none"]
+
+> WHAT and WHY only — no tech or implementation detail. Zero unresolved clarification markers at
+> hand-off — every ambiguity is resolved via `AskUserQuestion` before this file is written;
+> deferred answers become assumptions in §8.
+>
+> Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full
+> `**Detail**`, the document-level `Maturity` is `Draft`, `In review` or `Approved`, the item-level
+> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to §9.
+
+## 1. Summary
+
+[1–2 sentences: the user-facing outcome and why it matters.]
+
+**Scope boundary:**
+
+<!-- The visual orientation: what is in, what is explicitly out, and what each in-scope item
+     achieves — so a reader sees the shape of the change before parsing prose. Replace with
+     "N/A: [why]" for a change too small to have a meaningful boundary. -->
+
+```mermaid
+flowchart LR
+    subgraph IN["In scope"]
+        A["[in-scope item]"]
+        B["[in-scope item]"]
+    end
+    subgraph OUT["Out of scope"]
+        C["[excluded item]"]
+        D["[excluded item]"]
+    end
+    A --> E["[outcome this produces]"]
+    B --> F["[outcome this produces]"]
+```
+
+## 2. User Stories
+
+<!-- Use hierarchical story headings (e.g. "### Story 1: [Story Title] (P1)" or "### Story 3.2: [Story Title] (P1)")
+     followed by the standard role/want/benefit formulation. -->
+
+### Story 1: [Story Title] (P1)
+- **US1 (P1):** As a [role], I want [capability], so that [benefit].
+
+### Story 2: [Story Title] (P2)
+- **US2 (P2):** As a [role], I want [capability], so that [benefit].
+
+### Story 3: [Story Title] (P3)
+- **US3 (P3):** As a [role], I want [capability], so that [benefit].
+
+## 3. Functional Requirements
+
+**Index** — `Status` is `Live` or `Superseded → <ref>`.
+
+| ID | Requirement | Story | Priority | Status |
+|---|---|---|---|---|
+| FR-001 | [one-line summary] | US1 | P1 | Live |
+| FR-002 | [one-line summary] | US2 | P2 | Live |
+
+**Detail**
+
+- **FR-001:** The system MUST [full behaviour — every qualifier and exception that makes this
+  correct stays here; the index above is navigation, never a substitute].
+- **FR-002:** The system MUST [behaviour].
+
+## 4. Non-Functional Requirements
+
+| ID | Constraint | Kind | Status |
+|---|---|---|---|
+| NFR-001 | [one-line summary] | performance / security / UX / reliability | Live |
+
+**Detail**
+
+- **NFR-001 ([short label]):** [the constraint in full, with the reasoning that makes it binding].
+
+## 5. Out of Scope
+
+- **[excluded item]** — [why it is excluded, so the boundary is unambiguous rather than an omission].
+
+## 6. Acceptance Criteria
+
+<!-- Structured as Gherkin BDD scenario blocks with Given / When / Then clauses mapped to User Stories (US#)
+     and Functional Requirements (FR-###). Single-line criteria remain permissible for simple non-functional checks. -->
+
+- [ ] **Scenario: [Scenario Title]** (US1, FR-001)
+  - **Given** [precondition or initial context]
+  - **When** [action or trigger event occurs]
+  - **Then** [expected observable outcome]
+
+- [ ] **Scenario: [Scenario Title]** (US2, FR-002)
+  - **Given** [precondition]
+  - **When** [action]
+  - **Then** [expected outcome]
+
+- [ ] [observable, testable outcome] (NFR-001).
+
+## 7. Open Questions
+
+None. (The clarification-marker syntax is reserved for a session aborted mid-loop; a completed
+artifact carries none. The marker itself is deliberately not spelled here — a filled template is
+checked for its absence, and a template that quotes it makes every correct artifact look wrong.)
+
+## 8. Assumptions
+
+<!-- With a decision register, a row from a "Decide for me" pick cites its DEC-### in Basis: see ARTIFACT_FORMAT.md §12. -->
+
+| ID | Assumption | Affects | Basis |
+|---|---|---|---|
+| A1 | [assumption stated] | FR-001 | [why this default, or "user deferred"] |
+
+**Detail**
+
+- **A1** — [the reasoning, and what would change if the assumption turns out wrong].
+
+<!-- Write "None — no clarification questions were deferred." in place of the table and detail if
+     every ambiguity was resolved by a direct answer rather than the defer escape hatch. -->
+
+## 9. History
+
+<!-- When an item is superseded, its obsolete prose moves here and its index row above stays as a
+     tombstone with `Superseded → <ref>`. The body then reads as current truth; this section keeps
+     the reasoning behind the change. -->
+
+None — initial version.

package/core/shared/templates/doflow/specs-template.md

@@ -0,0 +1,55 @@
+# Specs: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Design:** ./design.md · **Maturity:** Draft · **Created:** [DATE]
+
+> Machine-checkable interface/schema contracts split out of design.md's own narrative — endpoints,
+> CLI verb signatures, repository/service interfaces, data schemas and file formats a design
+> decided. Reads ./design.md; distinct from it the way a contract is distinct from the rationale
+> that produced it.
+>
+> Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full
+> `**Detail**`, the document-level `Maturity` is `Draft`, `In review` or `Approved`, the item-level
+> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to §2.
+
+## 1. Interface Contracts
+
+<!-- Document endpoints, CLI verb signatures, and repository/service interfaces that anchor
+     implementation — one IC-### entry per contract, so plan.md and downstream implementation can
+     cite a specific contract precisely instead of a paragraph of prose.
+
+     The index carries a `Family` column, and the detail below is grouped under
+     "#### Family: [name]" headings. Contracts are ordered within a family, and families are ordered
+     as the index lists them. Each contract carries its own "#### IC-###: [summary]" heading so a
+     reader can link to and cite one contract without scanning the block around it. A heading of
+     that form counts as the contract's detail entry only when the same ID also appears in the first
+     column of the index above; an ID-shaped heading with no matching index row is ignored. Grouping
+     is navigation: it never shortens the normative text a contract carries. Write "N/A: [why]" in
+     place of the index and detail when the feature introduces no interface contract. -->
+
+| ID | Contract | Family | Kind | Status |
+|---|---|---|---|---|
+| IC-001 | [one-line summary] | [family name] | endpoint / cli-verb / schema / file-format | Live |
+| IC-002 | [one-line summary] | [family name] | endpoint / cli-verb / schema / file-format | Live |
+
+**Detail**
+
+#### Family: [family name]
+
+#### IC-001: [one-line summary]
+
+[the full normative shape — for an `endpoint`: method, route, request/response
+payload, status codes; for a `cli-verb`: verb name, flags, arguments, exit codes; for a `schema`:
+repository/service interface (`interface` → `concrete` → `mock` pattern) or service method
+signature (`[serviceMethod](params): ReturnType`); for a `file-format`: the file's key
+fields/shape — every qualifier and exception intact].
+
+#### IC-002: [one-line summary]
+
+[the full normative shape, every qualifier and exception intact].
+
+## 2. History
+
+<!-- Superseded contracts move here; the index row above stays as a tombstone with
+     `Superseded → <ref>`. -->
+
+None — initial version.

package/core/shared/templates/doflow/state-template.md

@@ -0,0 +1,59 @@
+# State: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Plan:** [PLAN_PATH] · **Status:** In Progress · **Updated:** [DATE]
+
+> Execution state for `/do-execute-plan`: what happened, not the intent (`plan.md`'s job). Rewrite
+> Status, Blocked, Findings and Next Action in place so each states only what is true now; delete
+> what no longer applies.
+>
+> The **Plan:** field above is this file's identity: a record naming a different plan is another
+> run's progress, so leave it alone and start a fresh one rather than reading it as your own. On
+> resume, trust this file and `git log` over recollection: conversation memory does not survive a
+> compact, and a lost place can mean re-dispatching finished work.
+
+## Repo Branch Status
+> Populate/update as `/do-execute-plan` first touches each repo — lazily, only when that repo's
+> first task executes, not upfront; this check runs for every task regardless of how many repos
+> the feature started with (a plan can grow a new repo mid-execution). `Status` is `created`
+> (branch didn't exist, now does) / `existing` (branch already existed, checked out as-is) /
+> `blocked` (uncommitted changes were found and not silently checked out over — resolve manually).
+> A `blocked` row is re-checked the next time that repo is touched; `created`/`existing` rows are
+> trusted as-is, never re-checked. For a single-repo feature, write "N/A: single-repo feature"
+> instead of the table.
+
+| Repo | Branch | Status | Last Checked |
+|---|---|---|---|
+| [repo path] | `feat/[branch]` | created / existing / blocked | [DATE] |
+
+## Task Ledger
+
+> Per-task execution facts, appended as each task finishes — the durable record the status sections
+> below summarise. `Rounds` is `<used>/<cap>` review-fix rounds (`0` = review passed first time,
+> `—` = not reviewed). `Review` is `clean`, `N open`, or `n/a`. `Status` here is execution state, not
+> the `Live`/`Superseded` vocabulary artifacts use — this file sits outside that convention.
+> A task with a `complete` row is DONE: never re-dispatch it, resume at the first task without one.
+
+| Task | Commits | Rounds | Review | Status |
+|---|---|---|---|---|
+| [A.1] | `[base7]..[head7]` | 0 | clean | complete |
+
+## Findings
+
+> Review findings that were deliberately not fixed, so nothing is discarded silently. Deferred
+> minors are handed to `/do-code-review` to triage; a parked finding records the ruling that let the
+> code stand. Write "None." when there are none — an empty section reads as an oversight.
+
+- **[A.2] deferred (minor)** — [one-liner].
+- **[B.1] parked** — [finding] — ruling: [why the code stands, or that it is real and deferred].
+
+## Completed
+- [ ] [task ref, e.g. A.1] — [one-line summary]
+
+## In Progress
+- [task ref] — [what's happening now]
+
+## Blocked
+- [task ref] — [blocker] — [what's needed to unblock]
+
+## Next Action
+[the single next step — task ref + brief description, or "none, feature complete pending /do-code-review"]

package/core/shared/workflows/do-flow-chain.md

@@ -0,0 +1,17 @@
+---
+description: Run the DoFlow spec-driven delivery chain on an idea
+---
+
+When the user types `/do-flow-chain <idea>`, orchestrate DoFlow's installed skills as one
+delivery sequence, pausing where human judgment matters:
+
+1. Act as the discovery lead and run `/do-brainstorm` with `<idea>` to produce
+   `requirement.md`. Wait for the user to confirm the requirement before continuing.
+2. Run `/do-design` to turn the confirmed requirement into `design.md`.
+3. Run `/do-plan` to decompose the design into a dependency-ordered `plan.md`.
+4. Ask the user to review all three specifications. Only proceed on explicit approval.
+5. Execute `/do-execute-plan --scope next` repeatedly until the plan's checklist is complete.
+6. Run `/do-test`, then `/do-code-review`, and report both results before proposing any commit.
+
+If the user comments directly inside any specification file, re-read it, apply the requested
+changes, and ask for approval again before moving on.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@khoavu882/doflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-beta.3",
+  "description": "DoFlow config installer — npx CLI for the registry-driven multi-harness install/update/remove lifecycle",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "gemini",
+    "opencode",
+    "ai-coding-agent",
+    "skills",
+    "hooks",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://github.com/khoavu882/do-flow#readme",
+  "bugs": {
+    "url": "https://github.com/khoavu882/do-flow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khoavu882/do-flow.git"
+  },
+  "author": "Khoa Vu Dang",
+  "bin": {
+    "doflow": "bin/doflow.js"
+  },
+  "engines": {
+    "node": "^22.18.0 || >=24.3.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "typecheck": "npx -y -p typescript@5.7.2 tsc -p tsconfig.json",
+    "bench": "node bench/runner.js",
+    "drift": "node scripts/check-format-drift.js",
+    "version": "node src/release/sync-plugin-versions.ts && git add core/.codex-plugin/plugin.json core/.claude-plugin/plugin.json core/.plugin/plugin.json"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "core/",
+    "types/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}