@caiqueoak/flow 0.6.0 → 0.7.0

package/README.md

@@ -30,9 +30,9 @@ PRD, engineering and plans use YAML frontmatter with `schema_version: 1`, `statu
 ## Canonical artifacts
 
 - `config.yaml`: runtime/bootstrap preferences; installed package metadata owns version.
-- `docs/prd.md`: product truth; `docs/engineering.md`: approved engineering truth.
+- `docs/prd.md`: global, cross-work-item product truth and learner-visible constraints; `docs/engineering.md`: approved global technical/code/infra 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.
+- `work-items/W###-slug/spec.md`: bounded scope, delivery decisions, and acceptance for one work item; it references applicable PRD rules without redefining them. `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {

package/skills/flow/SKILL.md

@@ -10,12 +10,12 @@ description: Repository-resumable software delivery through discovery, approved
 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.
 
 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.
+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. For a selected work item, use the PRD only for applicable global product rules and use its spec for the bounded delivery scope.
 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.
 
 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.
 
-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.
+Artifact owners: `docs/prd.md` owns global, cross-work-item product rules and learner-visible constraints; `docs/engineering.md` owns global technical, code, infrastructure, and pattern constraints; `backlog.yaml` owns the work-item DAG; `work-items/W###-slug/spec.md` owns only bounded scope, acceptance, and decisions for that work item, referencing applicable PRD rules without redefining them; `tasks.yaml` owns the task DAG; `implementation-plan.md` owns the approved approach; `state.yaml` owns the cursor; `gates.yaml` owns mechanical checks; `docs/graph.md` is derived. Preserve completed history; changed completed scope becomes new maintenance work.
 
 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

@@ -1,6 +1,6 @@
 # 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.
+Read the applicable global PRD rules, 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.
 

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

@@ -1,5 +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.
+Read current intent and existing product evidence. Create `.flow/docs/prd.md` as a coherent proposal for global, cross-work-item product rules and learner-visible constraints, not architecture or work-item implementation detail. 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/engineering/step-02-synthesize.md

@@ -2,7 +2,7 @@
 
 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:
+Recommend a complete but proportional technical contract. Keep global product behavior in the PRD and bounded delivery behavior in work-item specs; engineering records only the technical/code/infra constraints that realize them. Frontmatter: schema_version: 1, status: draft, baseline.profile: flow/readability-first@1, baseline.existing_code_policy: improve|preserve|not_applicable. Include exact headings:
 
 # Engineering
 

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

@@ -2,7 +2,7 @@
 
 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.
+Create EVERY known work-item folder with spec.md and tasks.yaml before implementation. Existing completed artifacts stay intact. Each spec owns only its bounded scope, delivery decisions, and acceptance; reference applicable global PRD rules rather than copying or redefining them. 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.
 

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

@@ -1,6 +1,6 @@
 # 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.
+Reread the applicable global PRD rules, the FULL approved engineering.md, selected spec/tasks, affected code and tests. The PRD supplies product constraints; the spec supplies only this work item's bounded delivery scope. 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:
 

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

@@ -1,5 +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.
+Reread applicable global PRD rules, 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.

package/src/commands/route.mjs

@@ -94,7 +94,12 @@ export function routeProject(root) {
       reason: backlog.work_items.every((item) => item.state === 'completed') ? 'finished' : 'external_action'
     };
   const base = `work-items/${item.folder}`;
-  const context = ['.flow/docs/engineering.md', `.flow/${base}/spec.md`, `.flow/${base}/tasks.yaml`];
+  const context = [
+    '.flow/docs/prd.md',
+    '.flow/docs/engineering.md',
+    `.flow/${base}/spec.md`,
+    `.flow/${base}/tasks.yaml`
+  ];
   const tasks = parseTasks(read(`${base}/tasks.yaml`), { expectedWorkItem: item.id });
   const extra = { work_item: item.id, required_context: context };
   const prepare = () => step('work_item_plan_approval', 'planning/step-02-prepare-plan.md', extra);