@caiqueoak/flow 0.4.0 → 0.5.0

package/README.md

@@ -1,73 +1,74 @@
 # Flow
 
-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.
+Repository-resumable software delivery with deterministic workflow checks and explicit human approval.
 
-## Install
+## Install and use
 
 ```bash
 npm install --save-dev @caiqueoak/flow
-npx flow init
+npx --no-install flow init --runtime codex
 ```
 
-`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.
+Invoke `/flow` to start or continue. The agent routes from repository state, reads the returned instruction/context, executes one step, persists artifacts, validates and routes again. Consequential decisions require explicit human input; status updates alone are not terminal stops.
 
-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.
+## Engineering preferences
 
-## Project bootstrap
+The single built-in template is **Readability First**, ID `flow/readability-first@1`. It covers Clean Code, SOLID, mandatory SRP, semantic naming, low coupling, high cohesion, vertical slices, modular ownership, locality and complexity justified by demonstrable value.
 
-`flow init` creates only:
+The agent-readable template ships with the npm package and is installed with the runtime skill. It is loaded when generating or explicitly revising engineering, not on every task. The approved `.flow/docs/engineering.md` is the project engineering source of truth and must be read in full before planning, implementation and review. Package/profile updates never silently change that contract.
 
-```text
-.flow/
-└── config.yaml
-```
-
-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.
-
-## Workflow
+For existing code, `--existing-code improve` (**Improve existing structure**) treats current style as evidence, not authority; `preserve` (**Keep existing structure**) gives consistent conventions stronger weight. Both preserve behavior and external contracts; neither authorizes automatic refactoring. New projects use `not_applicable` when no meaningful code exists.
 
-There is one public skill:
+## Lifecycle and approval
 
-```text
-/flow
-```
+Discovery → PRD approval → engineering approval → complete backlog planning → implementation-plan approval → serial implementation → review.
 
-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`.
+After product and engineering are approved, create every known work item's directory, `spec.md` and `tasks.yaml` before implementation. Then draft a concrete `implementation-plan.md` per selected work item and request human validation. It identifies exact paths, symbols/contracts, ordered changes, task mapping, engineering compliance, tests, risks, rollback and exclusions. Approval is tied to SHA256 revisions of the exact engineering and spec documents; stale plans return to drafting.
 
-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.
+PRD, engineering and plans use YAML frontmatter with `schema_version: 1`, `status: draft|approved`, and `approved_at` when approved. Engineering records baseline profile and existing-code policy. Plans record work_item, engineering_revision and spec_revision. Completed work retains its historical approval; later outcome records or engineering changes do not retroactively invalidate completed delivery.
 
-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.
+## Canonical artifacts
 
-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. Each Mermaid card contains only the work-item ID and canonical title. Every dependency arrow goes from dependency to dependent item and uses the color and line style of its source card. `flow graph` deterministically regenerates this projection from `BACKLOG.yaml`, using straight Mermaid arrows only.
+- `config.yaml`: runtime/bootstrap preferences; installed package metadata owns version.
+- `docs/prd.md`: product truth; `docs/engineering.md`: approved engineering truth.
+- `backlog.yaml`: schema 2, W### IDs, W###-kebab-case folders, kinds, priority, dependency DAG and lifecycle.
+- `work-items/W###-slug/spec.md`: bounded scope and decisions; `tasks.yaml`: schema 1, work_item, local T### task DAG.
+- `implementation-plan.md`: human-approved implementation approach.
+- `state.yaml`: resume cursor and migration reconciliation status.
+- `gates.yaml`: schema 1, command/builtin checks only; qualitative judgment remains review instructions.
+- `docs/graph.md`: deterministic derived projection; regenerate rather than hand-edit.
 
-## Update
+Persist only pending, in_progress and completed. Ready/Blocked are derived from dependency edges and explicit blockers. Blockers use `{id, type: external_action|consequential_decision, description, status: unresolved|resolved}`. Only one mutating work item/task may be active across the project. Read-only analysis may be parallel; automatic concurrent worktrees are out of scope.
 
-Updates are explicit:
+## CLI
 
-```bash
-flow update
-```
+All commands use the local installation:
 
-`flow update` updates the installation that provides the active CLI: the global package for `flow update`, or the project dependency for `npx flow update`. It uses npm's update operation and refreshes `/flow` for every coding agent configured in `.flow/config.yaml` without modifying canonical project state. If the project lockfile and the package on disk disagree, Flow safely reinstalls only its own package before updating.
+| Command                                 | Purpose                                                                     |
+| --------------------------------------- | --------------------------------------------------------------------------- |
+| `npx --no-install flow init`            | Configure or add/refresh runtime integrations.                              |
+| `npx --no-install flow migrate`         | Atomic structural migration, followed by semantic reconciliation via /flow. |
+| `npx --no-install flow status`          | Progress and dependency/external blockers.                                  |
+| `npx --no-install flow validate`        | Artifact integrity, approvals, DAGs, traceability and deterministic gates.  |
+| `npx --no-install flow route --json`    | Next legal step and required context.                                       |
+| `npx --no-install flow graph`           | Regenerate dependency graph.                                                |
+| `npx --no-install flow trace W015-T003` | Resolve a task's implementation commit.                                     |
 
-On Windows, npm is invoked through `cmd.exe` without Node's `shell: true` option, so `npm.cmd` executes without the `DEP0190` warning. When Flow is installed as a project dependency, `npx flow update` is equivalent.
+Use `--help` for options; `--path` selects a project. Existing managed projects cannot change engineering through init; use /flow and approval. Older config is refused without mutation and must be migrated first. Update with your package manager, then rerun init to refresh integrations; there is no separate update/config/gates workflow command.
 
-There is no background update check or automatic update mechanism.
+## Git and migration
 
-## Releases
+New completed code tasks have exactly one HEAD-reachable implementation commit with both trailers:
 
-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.
+```text
+Flow-Work-Item: W015
+Flow-Task: W015-T003
+```
 
-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.
+Non-code tasks use implementation: none. SHA is derived, not canonical task identity. Pre-commit verification uses `validate --pre-commit W015-T003`; normal validation checks the integrated commit. Avoid squashing task commits when preserving task traceability.
 
-## CLI
+Migration stages transformations before swapping artifacts, rejects collisions/invalid DAGs before mutation, preserves legacy documents and commit evidence, normalizes qualified task IDs/dependencies, and routes first to semantic reconciliation. Completed migrated tasks use implementation: legacy and optional legacy_commit; they do not require invented Git trailers or rewritten historical spec headings. Pending legacy folders may be absent during reconciliation, but complete backlog planning must materialize them before native implementation. Private project artifacts are not committed as fixtures.
 
-```text
-flow init
-flow update
-flow graph
-flow --version
-flow --help
-```
+## Releases
 
-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.
+Merges to main are released automatically after the test matrix passes. Conventional Commit PR titles drive semantic-release. Installed package metadata is the Flow version source of truth; project config does not duplicate it.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {
     "test": "node --test",
+    "lint": "eslint .",
+    "format": "prettier --write src test skills package.json package-lock.json README.md eslint.config.js prettier.config.mjs",
+    "format:check": "prettier --check src test skills package.json package-lock.json README.md eslint.config.js prettier.config.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "bin": {
@@ -13,6 +16,12 @@
   "dependencies": {
     "yaml": "^2.9.0"
   },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "eslint": "^9.36.0",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2"
+  },
   "files": [
     "src",
     "skills",
@@ -20,7 +29,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18.18"
   },
   "keywords": [
     "coding-agent",

package/skills/flow/SKILL.md

@@ -1,148 +1,21 @@
 ---
 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.
+description: Repository-resumable software delivery through discovery, approved engineering, complete backlog planning, human-approved implementation plans, serial implementation and review. Use /flow to start or continue this workflow.
 ---
 
 # Flow
 
-## Public contract
+/flow is the only public agent workflow. Incorporate current developer intent before routing; repository routing does not authorize ignoring new requests.
 
-`/flow` is the only public workflow skill.
+Read invariants.md once per invocation. All Flow CLI commands MUST use the project-local installation: `npx --no-install flow`. If unavailable, stop and ask for local installation; never use a global executable or fetch a different package automatically.
 
-- `/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.
+1. Run `npx --no-install flow route --json`.
+2. Read the returned instruction from this installed skill and every returned required_context file. Planning, implementation and review require rereading the FULL .flow/docs/engineering.md immediately before that step, including after resumption.
+3. Execute only the routed step, persist canonical artifacts and run its required checks.
+4. Route again. Continue until an actual human decision, external action, unrecoverable blocker or completion.
 
-Do not require the developer to know or invoke internal workflow phases.
+If stopped for approval, present the exact proposal and ask explicitly. Never approve your own work or treat silence as consent. Human approval must be persisted with status: approved and approved_at: ISO timestamp in the approved document. Clear state.stop_reason only when the current message resolves its decision. Revisions require a new approval, not copying an old approved_at.
 
-## Core principles
+Artifact owners: docs/prd.md product; docs/engineering.md engineering; backlog.yaml work-item DAG; work-items/W###-slug/spec.md scope; tasks.yaml task DAG; implementation-plan.md approved approach; state.yaml cursor; gates.yaml mechanical checks; docs/graph.md derived. Preserve completed history; changed completed scope becomes new maintenance work.
 
-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. Whenever work-item existence, title, dependencies, or status change, update `BACKLOG.yaml` first and then run `flow graph --path .` to regenerate it. Never edit `GRAPH.md` manually. Before changing the backlog, read `references/graph.md` and follow that contract exactly.
-
-## 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`
-- Creating or updating `GRAPH.md`: additionally load `references/graph.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`, run `flow graph --path .`, then synchronize `STATE.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.
+Engineering changes go through reconcile/step-01-reconcile.md: propose the change, obtain approval and invalidate affected plans. A profile is bootstrap input, never a second policy engine competing with approved engineering.

package/skills/flow/build/step-01-execute-task.md

@@ -0,0 +1,9 @@
+# Build — execute one approved task
+
+Read the FULL engineering.md, spec, tasks and approved current implementation plan. Verify current route and approval hashes before application edits. Persist both selected work item and task in_progress; no other mutating task may be active.
+
+Implement the bounded approved change for readability: semantic naming, mandatory SRP, low coupling, high cohesion, locality and justified complexity. If the approach must change materially, revise the plan and ask approval before continuing.
+
+Run targeted tests and npx --no-install flow validate --pre-commit W###-T###. Mark completed only after checks pass. Code tasks get exactly one primary implementation commit with separate trailers Flow-Work-Item: W### and Flow-Task: W###-T###. Non-code tasks use none. Do not assign legacy to new work.
+
+Synchronize metadata and graph, validate traceability with npx --no-install flow trace W###-T###, validate again and route to the next task/review. Do not yield merely for status.

package/skills/flow/discovery/step-01-project.md

@@ -0,0 +1,5 @@
+# Discovery — define product
+
+Read current intent and existing product evidence. Create .flow/docs/prd.md as a coherent proposal, not architecture. Frontmatter: schema_version: 1, status: draft. Headings: # Product Requirements; ## Purpose; ## Users; ## Scope; ## Requirements; ## Constraints; ## Non-goals.
+
+Create state.yaml with schema_version: 1, execution.phase: discovery, active.work_item/task: null, stop_reason: null, migration.status: not_required. Do not create incomplete work-item folders or implement code. Present scope and ask PRD approval through the next routed step.

package/skills/flow/discovery/step-02-await-approval.md

@@ -0,0 +1,3 @@
+# PRD approval
+
+Present the complete product proposal and consequential open questions. Ask explicit human approval. Do not proceed to engineering until approved. On approval record status: approved and approved_at, clear the resolved stop reason and route again. On requested revisions set draft, remove approved_at and revise before re-presenting.

package/skills/flow/engineering/profiles/readability-first.md

@@ -0,0 +1,20 @@
+---
+id: flow/readability-first@1
+label: Readability First — Recommended
+description: Readable, cohesive code with explicit responsibilities and proportional complexity.
+---
+
+# Readability First
+
+Load this reusable preference template only when synthesizing or explicitly revising engineering.md. After human approval, engineering.md is the project engineering source of truth; do not reload this profile during ordinary implementation.
+
+- Write code for easy understanding through familiar, consistent patterns. Prefer clarity over cleverness.
+- Apply Clean Code and SOLID. SRP is mandatory: each function, class, file and module has one cohesive responsibility and reason to change. SRP does not require tiny fragments or extra layers.
+- Use semantic, domain-oriented names for functions, classes, files, folders and variables. Materialize stack-specific casing and examples in engineering.md.
+- Keep coupling low and cohesion high. Make dependency direction and ownership explicit.
+- Prefer vertical slices around behavior or domain capabilities. Colocate code, tests and private helpers that change together. Shared code needs genuine shared ownership, not generic utils folders.
+- Modularize at meaningful boundaries. Do not introduce interfaces, factories, wrappers, layers or infrastructure without demonstrable value exceeding their complexity and maintenance cost.
+- State the concrete return on complexity before adding it. Defer speculative abstractions; optimize for reading and changing code.
+- Verify behavior, domain logic and external boundaries. Use ecosystem tooling for deterministic checks; qualitative review is not a control-plane fact.
+
+These preferences are not a fixed architecture. Reconcile them with PRD constraints, public contracts, security, stack conventions and explicit exceptions before seeking approval.

package/skills/flow/engineering/step-02-synthesize.md

@@ -0,0 +1,37 @@
+# Engineering — recommend a contract
+
+Read the approved PRD, config, full existing engineering evidence, repository tooling/contracts, profiles/readability-first.md and technology-defaults.md. Use existing_code_policy improve to critique accidental structure while preserving behavior; preserve gives consistent patterns stronger weight. Neither authorizes refactoring.
+
+Recommend a complete but proportional contract. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
+
+# Engineering
+
+## System shape
+
+## Modules and ownership
+
+## Dependency direction and boundaries
+
+## Vertical slices and code organization
+
+## Naming and readability conventions
+
+## Data ownership and persistence
+
+## Error handling
+
+## Testing and verification
+
+## Dependencies and external services
+
+## Security and operations
+
+## Deterministic gates
+
+## Deferred complexity
+
+## Exceptions
+
+Materialize concrete paths, responsibilities, dependency direction, naming examples, stack conventions, tests and justified exceptions. Explicitly state not applicable/deferred areas and why. Review SRP, low coupling/high cohesion, colocated vertical slices, readability and complexity ROI. Do not mandate ceremony or speculative abstraction.
+
+Draft gates.yaml schema_version: 1 with only command/builtin gates using real project tooling. Qualitative review stays instructions, not agentic gates or regex coverage. Do not install tooling or change application code before approval. Route to approval.

package/skills/flow/engineering/step-05-present.md

@@ -0,0 +1,3 @@
+# Engineering approval
+
+Present the recommendation macro to micro, concrete organization and naming examples, verification, tradeoffs, deferred complexity and exceptions. Ask explicit human approval. On approval record approved_at and status: approved; clear the resolved stop reason and route to complete backlog planning. Never inherit approval from a profile or legacy engineering file.

package/skills/flow/engineering/technology-defaults.md

@@ -0,0 +1,44 @@
+# Technology-aware convention defaults
+
+Use these as bounded defaults, not mandatory architecture templates. A deviation requires a concrete project reason.
+
+## TypeScript / JavaScript
+
+- source filenames: kebab-case unless framework tooling requires otherwise
+- symbols: ecosystem-standard camelCase/PascalCase
+- formatting: Prettier when compatible with the repository
+- linting: ESLint
+- type verification: `tsc --noEmit` for TypeScript
+- tests: use the repository's established runner; prefer behavior-focused tests
+
+## React
+
+- organize by product capability when the application has multiple meaningful features
+- keep component-local details close to the component; avoid a global `components/` dumping ground when feature ownership is clear
+- hooks use `use*`; components use PascalCase symbols while filenames follow project filename convention
+- do not introduce state libraries when local/server-state primitives are sufficient
+
+## Node backend
+
+- isolate external IO at explicit boundaries
+- keep business behavior independent of transport/framework details where this materially improves testability or reuse
+- do not add repository/service/interface layers solely to satisfy a pattern
+
+## Python
+
+- modules/files: snake_case
+- classes: PascalCase; functions/variables: snake_case
+- prefer Ruff for lint/format in new projects when compatible
+- use pytest for tests when no established runner exists
+- choose pyright/mypy only when static typing value justifies the project cost
+
+## Java / Spring
+
+- standard Java package/class naming
+- constructor injection by default
+- keep framework adapters from owning business rules when business rules are non-trivial
+- use the project's Maven/Gradle verification lifecycle rather than duplicating checks
+
+## Decision rule
+
+When an existing mature repository has a clearly enforced convention, `preserve` may retain it. Under `improve`, technology defaults and project requirements outrank accidental existing style.

package/skills/flow/invariants.md

@@ -0,0 +1,16 @@
+# Flow invariants
+
+1. Persist lifecycle states only pending, in_progress and completed. Ready/Blocked are derived.
+2. One mutating work item and task at a time across the project. Read-only research/review may be parallel; Flow does not orchestrate concurrent mutating worktrees.
+3. PRD approval precedes engineering approval; both precede complete backlog creation.
+4. Create every known work-item folder, spec.md and tasks.yaml before any implementation. No just-in-time missing work-item artifacts in native projects.
+5. Every work item needs a human-approved implementation-plan.md before application code changes.
+6. Plans bind to exact SHA256 engineering and spec text; stale approval cannot authorize implementation.
+7. Read the full engineering.md before planning, implementation and review. Missing/unapproved engineering blocks code.
+8. SRP, semantic naming, cohesion, low coupling, locality and justified complexity guide qualitative review; do not fake mechanical proof with Markdown regex.
+9. Dependencies belong in depends_on. External approvals belong in structured unresolved blockers.
+10. Regenerate graph through npx --no-install flow graph; never hand-edit derived output.
+11. New code tasks use implementation: commit and both Flow trailers. Non-code tasks use none. legacy is reserved for completed migrated tasks, never new work.
+12. Completion requires acceptance, verification, review and traceability. Completed changes become fix tasks or maintenance work.
+13. Pending migration reconciliation blocks all normal planning/build until legacy constraints reach canonical owners.
+14. Invoke only local npx --no-install flow commands. Progress alone is not a terminal stop.

package/skills/flow/migration/step-01-reconcile.md

@@ -0,0 +1,7 @@
+# Migration — reconcile semantic constraints
+
+Structural migration does not approve old product or engineering truth. Read available legacy-state.md, legacy-decisions.md, legacy-engineering.md, legacy-summary.md, legacy-backlog.yaml and affected specs alongside repository evidence.
+
+Transfer current product truth to prd.md, engineering constraints to a draft engineering.md, active external approval restrictions to structured unresolved backlog blockers, and work-item rationale to specs. Keep legacy evidence read-only for provenance. Do not erase completed task history or invent missing commits.
+
+Present reconciliation and consequential questions to the human. After semantic constraints are transferred and confirmed, set migration.status: completed, clear the resolved stop and route through PRD/engineering approval as needed. Missing pending folders are allowed only during reconciliation; complete backlog planning creates them before implementation. Do not mutate production, reset data or delete legacy systems based on prose evidence alone.

package/skills/flow/planning/step-01-plan-work-item.md

@@ -0,0 +1,9 @@
+# Planning — materialize the complete backlog
+
+Reread the FULL approved engineering.md and PRD. Decompose all known approved scope into bounded work items and dependencies; do not invent future scope. Create backlog.yaml schema_version: 2, work_items with id W###, folder W###-kebab-case, kind feature|technical|maintenance, title, state pending, priority positive integer, depends_on and blockers.
+
+Create EVERY known work-item folder with spec.md and tasks.yaml before implementation. Existing completed artifacts stay intact. Specs include ## Status, ## Goal, ## Scope, ## Non-goals, ## Requirements, ## Acceptance criteria, ## Decisions, ## Implementation, ## Final outcome, ## Validation and ## Follow-up. Tasks: schema_version: 1, work_item: W###, tasks with local T### IDs, title, state pending, depends_on, implementation commit|none. Preserve already completed task history.
+
+Structured blockers: id stable-kebab-case, type external_action|consequential_decision, description, status unresolved|resolved. Do not encode dependencies as external blockers.
+
+Create/maintain gates.yaml and state.yaml; regenerate graph with npx --no-install flow graph. Run npx --no-install flow validate. Route again; no application code in this step.

package/skills/flow/planning/step-02-prepare-plan.md

@@ -0,0 +1,33 @@
+# Planning — draft an implementation plan
+
+Reread the FULL approved engineering.md, selected spec/tasks, affected code and tests. Write implementation-plan.md BEFORE application edits. Frontmatter: schema_version: 1, work_item: W###, status: draft, engineering_revision and spec_revision SHA256 of the exact UTF-8 files. Calculate with Node crypto; never guess.
+
+Use exact headings:
+
+# Implementation Plan
+
+## Outcome
+
+## Current state
+
+## Proposed changes
+
+## Execution sequence
+
+## Task mapping
+
+## Data and control flow
+
+## Engineering compliance
+
+## Tests and validation
+
+## Risks and rollback
+
+## Deliberately excluded
+
+## Human decisions required
+
+Proposed changes must identify exact paths, functions/classes, responsibilities, signatures/contracts, removals and tests. Explain ordered implementation steps with T### mapping, acceptance evidence, dependency direction, SRP/locality and complexity ROI. Use concrete names and snippets where they clarify the actual implementation. List uncertainty rather than inventing facts. Include migration/rollback when relevant and explicit non-goals. This must be executable by a basic agent without designing missing architecture.
+
+Remove prior approved_at on revision. Present the exact draft and request validation through the next step. Do not implement yet.

package/skills/flow/planning/step-03-await-approval.md

@@ -0,0 +1,3 @@
+# Implementation-plan approval
+
+Present the standardized plan and exact implementation changes. Ask the human to approve or request revisions. Do not start implementation until explicit approval is recorded with status: approved and approved_at. Approval applies only to matching engineering/spec revisions. On requested revisions return to drafting; never silently expand the approved plan.

package/skills/flow/reconcile/step-01-reconcile.md

@@ -0,0 +1,7 @@
+# Reconcile — restore canonical truth
+
+Resolve inconsistencies using the single-owner rule: product truth in `docs/prd.md`, engineering truth in `docs/engineering.md`, work-item graph/state in `backlog.yaml`, task state in `tasks.yaml`, current cursor in `state.yaml`, and task implementation identity in Git trailers.
+
+Do not rewrite completed history to hide change. Create fix tasks or maintenance work items. Regenerate `docs/graph.md` after backlog mutation and validate before routing again.
+
+For engineering changes, reread the full approved engineering.md and propose a draft revision through engineering/step-02-synthesize.md. Obtain explicit human approval before replacing the contract. New engineering/spec revisions invalidate affected implementation plans. Do not silently change config preferences or copy old approval timestamps. Use only npx --no-install flow commands.

package/skills/flow/review/step-01-review-work-item.md

@@ -0,0 +1,5 @@
+# Review — verify delivery
+
+Reread FULL engineering.md, frozen scope, tasks and approved plan. Review acceptance, regressions, SRP, semantic naming, low coupling/high cohesion, vertical-slice locality and complexity ROI. Explain concrete defects, not stylistic alternatives. Run actual tests and npx --no-install flow validate; never write fake gate evidence.
+
+Defects become new fix tasks. Material approach changes require revised plan approval; never rewrite completed task history. Complete only after all tasks, acceptance, gates, qualitative review and traceability pass. Populate spec outcome/implementation/validation; synchronize backlog/state/graph, validate and route again.