@caiqueoak/flow 0.2.1 → 0.3.1

package/README.md

@@ -1,134 +1,72 @@
 # Flow
 
-Flow is a readability-first, agent-agnostic software-development workflow for coding agents. It maximizes autonomous delivery while keeping consequential product and engineering decisions explicit and approved.
+Flow is a readability-first, agent-agnostic software delivery workflow for coding agents. It maximizes autonomous execution while keeping consequential product and engineering decisions under developer control.
 
-## Workflow
+## Install
 
-```text
-idea / existing project
-        ↓
-global discovery
-(product + engineering + production constraints)
-        ↓
-independent consequential decisions, batched for approval
-        ↓
-production-capable MVP
-        ↓
-work DAG (feature + technical + maintenance)
-        ↓
-/flow-next
-        ↓
-plan → build → gates → review → fixes → done
-        ↓
-next safe work item automatically
+```bash
+npm install --save-dev @caiqueoak/flow
+npx flow init
 ```
 
-The agent continues until it reaches a consequential decision, external approval, unrecoverable blocker, or no ready work. Every requested decision must include **Decision, Context, Options, Recommended option, Why recommended, and Impact**.
+`flow init` is interactive, or use `--runtime codex,claude` in automation. Built-in adapters install the public `/flow` skill in `.codex/skills/flow/` or `.claude/skills/flow/`; a custom project-local skills directory is also available interactively.
 
-## Project state
+Skills are always installed inside the current project. Runtime integration directories never contain project state. If `.flow/` already exists, `flow init` only adds missing coding-agent integrations and updates `.flow/config.yaml`. If all built-in integrations are already configured, it exits without prompting. It does not modify canonical project artifacts.
 
-```text
-.flow/
-├── config.yaml
-├── PRD.md
-├── ENGINEERING.md
-├── SUMMARY.md
-├── DECISIONS.yaml
-├── BACKLOG.yaml
-├── STATE.yaml
-├── gates/
-└── work-items/
-    ├── 001F-user-profile/
-    │   ├── SPEC.md
-    │   └── TASKS.yaml
-    ├── 002T-production-baseline/
-    │   ├── SPEC.md
-    │   └── TASKS.yaml
-    └── 003M-auth-reconciliation/
-        ├── SPEC.md
-        └── TASKS.yaml
-```
-
-`F`, `T`, and `M` mean **feature**, **technical**, and **maintenance**. The numeric prefix is a stable readable sequence, not execution order. Dependencies determine execution. `work-items` is intentionally generic enough to cover all three kinds while remaining explicit to readers.
-
-## CLI
+## Project bootstrap
 
-The CLI is intentionally small:
+`flow init` creates only:
 
-```bash
-flow init
-flow install
-flow update
+```text
+.flow/
+└── config.yaml
 ```
 
-### Requirements
-
-Flow requires Node.js 18 or newer.
-
-- `flow init` creates `.flow/`.
-- `flow install` installs the bundled skills into a coding-agent skill directory.
-- `flow update` fetches the latest published Flow package and replaces the installed Flow skills.
-
-The CLI does **not** plan work, schedule tasks, invoke models, or orchestrate subagents. Those responsibilities stay in the skills and coding-agent runtime.
-
-Use an explicit skill directory when needed:
+It does not create a PRD, engineering guide, backlog, graph, state, decisions, work items, gates, or templates. During `/flow`, new project documents and artifacts are created only when the developer explicitly requests or authorizes them. Flow updates existing approved artifacts instead of inventing ad-hoc progress, summary, handoff, or status documents.
 
-```bash
-flow install --target .agents/skills
-flow update --target .agents/skills
-```
+## Workflow
 
-Then start a project in the coding agent:
+There is one public skill:
 
 ```text
-/flow-new "I want to build a diet app"
+/flow
 ```
 
-Normal operation after discovery is primarily:
+Use `/flow <intent>` to start or change work, for example `/flow I want to build a diet app`. Use `/flow` with no extra input to continue from `.flow/STATE.md`.
 
-```text
-/flow-next
-```
+Flow internally loads only the guidance needed for discovery, planning, build, review, or reconciliation. It asks only for consequential decisions and uses the largest safe degree of parallelism. Once execution is underway, it does not stop merely to announce completed tasks, progress, or next steps; it continues automatically until developer input, external approval, an unrecoverable blocker, or no ready work requires a real stop.
 
-## Parallelism
+When authorized, Flow keeps a concise artifact model: product truth in `PRD.md`, engineering truth in `ENGINEERING.md`, decisions in `DECISIONS.md`, execution context in `STATE.md`, the canonical work-item DAG in `BACKLOG.yaml`, and a human-readable derived projection in `GRAPH.md`. Work items use `SPEC.md` plus `TASKS.yaml`. `SUMMARY.md` is not part of the model.
 
-```yaml
-parallelism:
-  strategy: maximum_safe
-  max_concurrent_work_items: auto
-  max_concurrent_tasks_per_work_item: auto
-  delegation: allowed
-```
+In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute.
 
-`auto` means the orchestrating agent chooses the largest set it can safely coordinate for the current scheduling cycle. It considers real dependencies, decision dependencies, likely write/contract overlap, uncertainty, runtime/tool capacity, merge risk, and **token/coordination overhead**. It must prefer fewer workers when additional concurrency would waste tokens or lower confidence.
+## Update
 
-Before work starts, selected work items/tasks are marked `in_progress` with an execution ID. Another chat or agent must respect those claims and choose other ready work. Flow has no automatic claim timeout and never silently steals in-progress work.
+Updates are explicit:
 
-## Token efficiency
+```bash
+flow update
+```
 
-Token efficiency is a framework constraint, not an afterthought. Skills must use the smallest sufficient context, avoid repeatedly loading historical documents, prefer targeted repository inspection, keep canonical artifacts concise, reuse accepted decisions, prefer deterministic gates to extra reviewer agents, and spawn subagents only when the expected parallel benefit exceeds duplicated context and coordination cost.
+`flow update` detects how the active Flow CLI is installed. If the project contains `@caiqueoak/flow`, it updates that project dependency; if the CLI is globally installed, it updates the global package instead. It then refreshes `/flow` for every coding agent configured in `.flow/config.yaml` without modifying canonical project state.
 
-## Updates
+On Windows, npm is invoked through the command shell so `npm.cmd` can be executed correctly. When Flow is installed as a project dependency, `npx flow update` is equivalent.
 
-`flow update` is explicit and deterministic. The default project template also contains:
+There is no background update check or automatic update mechanism.
 
-```yaml
-updates:
-  check_on_run: true
-  auto_update: false
-```
+## Releases
 
-For now, automatic checks are advisory rather than silently changing the installation. This avoids a framework update changing workflow behavior in the middle of active work. Projects can adopt a newer Flow version intentionally with `flow update`.
+Merges to `main` are released automatically after the test matrix passes. The release pipeline uses npm Trusted Publishing (OIDC), creates a signed npm provenance record, and tags the release; no npm token or manual version bump is needed.
 
-## Package
+Use Conventional Commit prefixes in the PR title (and retained commits): `fix:` produces a patch, `feat:` a minor, and `feat!:` or a `BREAKING CHANGE:` footer a major release. `docs:`, `test:`, `chore:`, and `ci:` do not publish a package.
 
-The executable is `flow`. The npm package is currently `@caiqueoak/flow` so it does not collide with the pre-existing unscoped `flow` package.
+## CLI
 
-```bash
-npx @caiqueoak/flow install --target .agents/skills
-npx @caiqueoak/flow init
+```text
+flow init
+flow update
+flow --version
+flow --help
 ```
 
-## Releases
-
-Flow follows [Semantic Versioning](https://semver.org/). A merge to `main` publishes only when the version in `package.json` does not already exist on npm. GitHub Actions runs the test and packaging checks, then publishes the package with provenance. Release PRs must update both `package.json` and `package-lock.json`.
+The CLI bootstraps project-local integrations and configuration. The coding agent plus `/flow` owns discovery, planning, scheduling, delegation, build, gates, review, reconciliation, and state synchronization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {
@@ -13,7 +13,6 @@
   "files": [
     "src",
     "skills",
-    "templates",
     "README.md",
     "LICENSE"
   ],

package/skills/flow/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: flow
+description: Autonomous, readability-first software delivery workflow. Continue from project state or incorporate new intent, ask only for consequential decisions, then plan, build, validate, reconcile, and continue as far as safely possible.
+---
+
+# Flow
+
+## Public contract
+
+`/flow` is the only public workflow skill.
+
+- `/flow` with no additional intent continues from `.flow/STATE.md` as far as safely possible.
+- `/flow <freeform intent>` incorporates the intent into current project context and continues appropriately.
+- If `.flow/STATE.md` does not exist, begin global discovery using the idea, repository, or source documents supplied.
+
+Do not require the developer to know or invoke internal workflow phases.
+
+## Core principles
+
+1. **Readability first.** Canonical artifacts must be understandable without Flow internals.
+2. **Decision ownership.** The developer owns consequential product and engineering decisions; the agent executes within approved rules and obvious conventions.
+3. **Autonomy by default.** Continue until a consequential decision requiring developer input, external approval, unrecoverable blocker, or no-ready-work condition.
+4. **Just-in-time detail.** Resolve global decisions during discovery and work-item detail only when that item becomes active.
+5. **Production-aware MVP.** MVP includes product capability plus the technical, infrastructure, quality, deployment, and operational work needed to run it.
+6. **Parallelism first.** Execute the largest safe independent set while preserving correctness and token efficiency.
+7. **Automatic synchronization.** Keep state, decisions, PRD, engineering definition, backlog, graph, specs, and tasks aligned.
+8. **Artifact restraint.** Never create a new project document or artifact unless the developer explicitly requests or authorizes it. Update existing approved artifacts instead whenever possible.
+9. **Execution continuity.** Do not pause execution merely to report progress, completion, or next steps. Continue automatically while ready work exists. Surface status only when execution has actually stopped or when developer input is required.
+
+## Canonical project artifacts
+
+Create artifacts only when they become valid and only when the developer has explicitly requested or authorized their creation. `flow init` creates only `.flow/config.yaml`.
+
+Developer-facing knowledge is Markdown:
+
+- `.flow/PRD.md` - current global product truth and MVP boundary.
+- `.flow/ENGINEERING.md` - global engineering truth.
+- `.flow/DECISIONS.md` - consequential decision record and rationale.
+- `.flow/STATE.md` - concise current execution/navigation checkpoint and resume context.
+- `.flow/GRAPH.md` - human-readable derived projection of the work-item dependency graph and current readiness state.
+- `.flow/work-items/<folder>/SPEC.md` - readable lifecycle/specification of one work item.
+
+Graph/control data is YAML:
+
+- `.flow/BACKLOG.yaml` - canonical work-item DAG and work-item state.
+- `.flow/work-items/<folder>/TASKS.yaml` - task DAG and execution ownership.
+
+Do not create `SUMMARY.md`, completion logs, ad-hoc progress documents, handoff documents, reports, or any other new project artifact unless the developer explicitly requests or authorizes them. Completed `SPEC.md` files retain concise Overview and Validation sections.
+
+`GRAPH.md` is derived only. It must never become an independent source of truth and must be reconciled whenever work-item existence, dependencies, or status change. Preserve its established visual style and conventions while updating it.
+
+## Work item model
+
+- `feature` (`F`) - product/user capability.
+- `technical` (`T`) - architecture, infrastructure, platform, quality, deployment, or enabling work.
+- `maintenance` (`M`) - reconciliation, migration, refactor, or corrective work.
+
+Folder format is `<three-digit-sequence><kind-code>-<slug>` (for example, `001F-user-profile`). The sequence is a stable readability aid, never execution order. Dependencies determine readiness.
+
+Work-item states are derived consistently:
+
+- `complete` (`✅`, green) - the item is completed.
+- `in_progress` (`🔵`, blue) - the item has active execution.
+- `blocked` (`🔴`, red) - the item is neither complete nor in progress and at least one work-item dependency is not complete.
+- `pending` (`🟡`, yellow) - the item is neither complete nor in progress and every work-item dependency is complete; it is ready to execute.
+
+The graph must use these meanings consistently for nodes and outgoing dependency-line styling.
+
+## Decision authority
+
+Apply low-impact and conventional choices automatically. A decision requires developer approval when materially different choices affect product behavior or scope; architecture/public contracts; production infrastructure or cost; persistent data; security/privacy; testing strategy or gates; project-wide conventions; or other work-item assumptions.
+
+## Decision presentation protocol
+
+Every requested decision must use this readable structure:
+
+### Decision
+
+What needs to be chosen.
+
+### Problem
+
+The concrete uncertainty.
+
+### Context
+
+Relevant product, engineering, production, and existing-decision context.
+
+### Options
+
+Realistic alternatives and trade-offs.
+
+### Recommended option
+
+Exactly one recommendation when evidence permits.
+
+### Why recommended
+
+Concise justification grounded in current goals and constraints.
+
+### Approach
+
+The high-level direction following the recommendation.
+
+### Impact
+
+Affected definitions, rules, gates, work items, tasks, or implementation.
+
+Never hide a consequential choice inside an implementation plan. Batch the largest currently-known set of independent decisions; do not invent hypothetical questions.
+
+## Decision lifecycle and impact
+
+Decision states are `candidate`, `pending_user`, `accepted`, `rejected`, and `superseded`. Preserve the rationale in `DECISIONS.md`. Reconcile pending work before execution, stop only affected in-progress paths, and create maintenance work rather than rewriting completed history.
+
+## Internal workflow routing
+
+Load only the reference needed for current state:
+
+- Missing state or global definition: `references/discovery.md`
+- Ready/unplanned work: `references/planning.md`
+- Ready planned tasks: `references/build.md`
+- Completed implementation awaiting validation: `references/review.md`
+- Decision impact or inconsistent artifacts: `references/reconcile.md`
+
+## Orchestration loop
+
+1. Read `.flow/config.yaml`.
+2. Read only the minimum navigation context from `.flow/STATE.md` when present.
+3. Classify new intent and its impact on canonical truth, backlog, active work, or execution detail.
+4. Respect work/tasks already `in_progress` under another execution ID.
+5. Route to the minimal internal reference.
+6. Claim selected work before parallel execution.
+7. Continue planning, build, gates, review, fixes/reconciliation, and completion without another invocation.
+8. Recompute work-item states and readiness after every meaningful transition, synchronize `BACKLOG.yaml`, `STATE.md`, and `GRAPH.md`, and continue if ready work exists.
+9. Do not stop or return control merely to announce that a task/work item completed or to describe the next step. Stop only when developer input is required for a consequential decision, an external approval is required, an unrecoverable blocker prevents useful progress, or no ready work remains.
+
+When execution stops, report the stopping reason and the smallest relevant status summary. During uninterrupted execution, avoid progress-only messages.
+
+## Parallelism and gates
+
+`auto` means the largest safe concurrency the orchestrator can reliably coordinate, considering dependencies, shared decisions/files/contracts, integration risk, available capacity, context complexity, and token overhead. It is not unlimited. Prefer one primary orchestrator and delegate only where independent substantial work justifies it.
+
+Gates may be deterministic commands or agentic policy checks. Define/refine them during discovery or planning when relevant. Build agents know applicable gates before implementation; review validates requirements, integration, and blocking gates.
+
+## Git and token efficiency
+
+Follow the approved Git strategy in `ENGINEERING.md`; by default create one atomic commit per completed task. Read the minimum relevant canonical context, avoid repeated large-document ingestion and duplicate prose, reuse accepted decisions, prefer deterministic checks, and delegate only with narrow ownership/context packets.

package/skills/flow/references/build.md

@@ -0,0 +1,7 @@
+# Build
+
+Compute ready tasks, exclude claims by another execution ID, select the largest safe set, and mark it `in_progress` before editing or delegating. Load only relevant specs, decisions, code, and gates. Follow approved conventions, avoid unrelated refactors, run the cheapest relevant deterministic checks, make atomic commits, and mark tasks complete only after acceptance checks pass.
+
+Synchronize `TASKS.yaml`, `BACKLOG.yaml`, `STATE.md`, `GRAPH.md`, and other affected approved canonical artifacts at each meaningful transition. Never create a new document or artifact unless the developer explicitly requested or authorized it. If a consequential new choice emerges, stop only the affected path and present the decision while independent paths continue when safe.
+
+Do not pause or return control merely to report that a task or work item completed, to announce progress, or to state the next step. Recompute readiness and continue automatically while useful ready work exists. Surface execution status only when developer input is required or execution has actually stopped.

package/skills/flow/references/discovery.md

@@ -0,0 +1,15 @@
+# Global Discovery
+
+## Goal
+
+Define the smallest coherent, production-capable MVP and the global product/engineering rules required to plan it. Do not specify work-item detail prematurely.
+
+## Scope
+
+Resolve only consequential global decisions affecting the problem, users, MVP, business constraints, production environment, deployment, architecture, persistence, integrations, security, observability, testing, conventions, documentation, Git strategy, and reusable gates. Infer trivial conventions from the existing codebase or chosen ecosystem.
+
+## Outputs
+
+Update valid canonical artifacts when their truth changes. Create `PRD.md`, `ENGINEERING.md`, `DECISIONS.md`, `BACKLOG.yaml`, `STATE.md`, `GRAPH.md`, work-item artifacts, or gate definitions only when the developer explicitly requested or authorized creation of that artifact class. Never create substitute, progress, summary, handoff, or ad-hoc documents to capture information that belongs in an existing approved artifact.
+
+`GRAPH.md` is a derived human-readable projection of `BACKLOG.yaml`, not an independent source of truth. Discovery ends when no unresolved global decision is needed for a coherent production-capable MVP and initial work-item DAG.

package/skills/flow/references/planning.md

@@ -0,0 +1,7 @@
+# Work-item Planning
+
+Read only relevant global decisions, backlog context, existing spec/tasks, and source. Ask consequential work-item decisions only when viable answers materially change behavior, contracts, data semantics, technical boundaries, security, UX, or gates.
+
+For an already authorized work-item artifact class, create or update `.flow/work-items/<id>/SPEC.md` with goal, scope/non-goals, relevant decisions, approach, requirements, acceptance criteria, gates, dependencies/impacts, and validation. Create or update `TASKS.yaml` with bounded, testable, independently executable tasks, real blocking dependencies only, and concise acceptance/validation expectations.
+
+If the required `SPEC.md` or `TASKS.yaml` does not yet exist and the developer has not explicitly requested or authorized creation of that artifact class, request authorization before creating it. Do not create substitute planning documents. After planning, continue automatically into ready execution instead of stopping to report the plan unless a consequential developer decision is required.

package/skills/flow/references/reconcile.md

@@ -0,0 +1,5 @@
+# Reconciliation
+
+Keep canonical truth and active plans aligned when new intent or accepted decisions affect work. Reconcile pending/planned work before execution, preserve unaffected in-progress work, and create maintenance work for completed work that must change. Preserve superseded decisions with links to their replacements. Update only approved artifacts whose current truth changed, including the derived `GRAPH.md` whenever work-item existence, dependencies, or status change.
+
+Never create a new document or artifact during reconciliation unless the developer explicitly requested or authorized it. After reconciliation, recompute readiness and continue execution automatically when safe rather than pausing to report status.

package/skills/flow/references/review.md

@@ -0,0 +1,5 @@
+# Review
+
+Verify completed work against its spec and applicable gates: inspect task completion and diff, validate requirements and acceptance criteria, run deterministic blocking gates, then applicable agentic gates, and check integration/regressions. Create targeted fix tasks within approved scope; request a decision only for consequential new choices. On success, update the spec Overview and Validation, then synchronize `BACKLOG.yaml`, `STATE.md`, `GRAPH.md`, and other affected approved canonical artifacts.
+
+Never create a new document or artifact during review unless the developer explicitly requested or authorized it. Do not stop merely to announce successful validation or the next ready work item; return to orchestration and continue while useful ready work exists.