@caiqueoak/flow 0.2.1 → 0.3.1

package/skills/flow-plan/SKILL.md

@@ -1,86 +0,0 @@
----
-name: flow-plan
-description: Plan a ready feature, technical, or maintenance work item just in time, resolve consequential local decisions, reconcile cross-work impacts, define gates, and create a dependency-aware task DAG.
----
-
-# Flow Plan
-
-## Objective
-
-Turn one ready work item into an implementation-ready specification and task DAG while preserving all approved global product and engineering decisions.
-
-## Context loading
-
-Start with `.flow/STATE.yaml`, `.flow/BACKLOG.yaml`, and `.flow/SUMMARY.md`. Read only the relevant sections of `PRD.md`, `ENGINEERING.md`, `DECISIONS.yaml`, and gates needed for this work item. Do not reload unrelated completed work.
-
-## Work item selection
-
-Plan a requested work item or the highest-priority ready work item selected by the orchestrator. Mark it `in_progress` with the current `execution_id` before beginning mutating work.
-
-Create `.flow/work-items/<sequence-padded><kind-code>-<slug>/SPEC.md` and `TASKS.yaml` from templates.
-
-## Just-in-time discovery
-
-Ask detailed questions only when answers materially affect this work item's behavior, scope, UX, contracts, data semantics, architecture application, infrastructure interaction, security/reliability, acceptance criteria, or gates.
-
-Reuse accepted global decisions. Applying an approved rule is not a new decision.
-
-Do not ask trivial implementation questions when a clear language/framework/repository convention or approved engineering rule provides the answer.
-
-## Consequential decisions
-
-Never silently choose a consequential local or global decision. Use the same six-part decision format as `flow-new`: Decision, Context, Options, Recommended option, Why recommended, Impact.
-
-Batch the maximum set of currently-known independent decisions; do not invent speculative future cases to create a larger batch.
-
-If a work-item decision establishes or changes a project-wide rule, treat it as a global technical/product decision, obtain developer approval, record it in `DECISIONS.yaml`, update `PRD.md` or `ENGINEERING.md`, and calculate impacted work.
-
-## Reconciliation and cross-work impact
-
-When a new accepted decision impacts another work item:
-- pending/ready/planned item: mark `needs_reconciliation` when its assumptions/spec may be stale;
-- in-progress item owned by another execution: do not modify its work; record the impact and surface the coordination issue;
-- completed item: create a `maintenance` work item when code/data/config must be reconciled or migrated.
-
-Decision impact is not the same as dependency. Use dependencies only for actual execution blockers.
-
-## Gates
-
-Resolve all global gates applicable to the work item. During planning, propose work-item-specific gates when needed. If a proposed gate establishes a reusable project-wide standard, it requires developer approval and should be promoted to `.flow/gates/`. Keep one-off validation criteria in `SPEC.md`.
-
-## Task DAG
-
-Each task must include:
-- ID and clear title;
-- status;
-- `depends_on` with only real blockers;
-- affected areas when reasonably predictable;
-- concise acceptance criteria;
-- decision/gate references when relevant;
-- execution ID when claimed.
-
-Validate the DAG is acyclic. Do not create explicit waves; execution groups are derived dynamically from the DAG and conflict analysis.
-
-## Specification readability
-
-`SPEC.md` is the readable lifecycle document for the work item. Use:
-- Overview
-- Goal
-- Scope / Non-Goals
-- Product Decisions
-- Engineering Decisions
-- Requirements
-- Acceptance Criteria
-- Dependencies & Impact
-- Validation Gates
-- Validation Result
-- Delivery Notes
-
-Keep it concise. Update `Overview` on completion to reflect what was actually delivered. Do not create a completion-log or separate summary file per work item.
-
-## Token-efficiency rules
-
-- Inspect only code likely relevant to current decisions/tasks.
-- Reuse global definitions instead of copying them into the spec.
-- Refer to decision/gate IDs instead of duplicating long policies.
-- Avoid research unless current evidence is insufficient for a consequential decision.

package/skills/flow-review/SKILL.md

@@ -1,47 +0,0 @@
----
-name: flow-review
-description: Validate implemented work against its spec and configured gates, create targeted fixes or maintenance work, and close the work item automatically when it passes.
----
-
-# Flow Review
-
-## Objective
-
-Provide the final safety net after build while avoiding redundant re-analysis already covered by deterministic or approved agentic gates.
-
-## Required behavior
-
-1. Read the active SPEC/TASKS, relevant diff/commits, applicable gate definitions, and only the global decisions/engineering rules needed to validate them.
-2. Verify every requirement and acceptance criterion.
-3. Run all applicable blocking command gates and targeted checks.
-4. Run applicable agentic gates only for policy that tools cannot determine reliably.
-5. Check cross-task integration, obvious regressions, unexpected scope changes, and contract mismatches.
-6. Produce manual validation steps only where automated/agentic validation cannot establish confidence.
-
-## Failure
-
-If review fails:
-- create narrow fix tasks with real dependencies;
-- leave the work item `in_progress`;
-- return it to build automatically;
-- create maintenance work instead of reopening completed unrelated items directly.
-
-If review exposes a consequential decision, stop the affected path and use the required decision presentation protocol. Never silently resolve it during review.
-
-## Success
-
-When review passes:
-- mark the work item `done`;
-- update the SPEC `Overview`, `Validation Result`, and concise `Delivery Notes`;
-- update BACKLOG and STATE;
-- synchronize SUMMARY only when project-level understanding materially changed (for example work-item completion, MVP progress, architecture/production model, or key decision change);
-- recompute the ready work graph.
-
-Do NOT create `COMPLETION-LOG.md` or a separate per-work-item summary.
-
-## Token-efficiency rules
-
-- Do not repeat analysis already proven by command gates.
-- Review the smallest relevant diff/contract surface.
-- Avoid general-purpose reviewer subagents when a targeted gate answers the question.
-- Keep review output concise and write only durable information to canonical artifacts.

package/skills/flow-status/SKILL.md

@@ -1,26 +0,0 @@
----
-name: flow-status
-description: Orient a developer or fresh agent from small readable Flow state without rediscovering the repository.
----
-
-# Flow Status
-
-## Objective
-
-Explain where the project is, what is running, what is blocked, and what can run next with minimal context.
-
-## Required behavior
-
-1. Read `.flow/SUMMARY.md`, `.flow/STATE.yaml`, and `.flow/BACKLOG.yaml`.
-2. Read active work-item TASKS/SPEC only when needed for active progress details.
-3. Report concisely:
-   - project stage and MVP progress;
-   - active/in-progress work items and execution IDs;
-   - ready work items;
-   - pending consequential decisions;
-   - blockers/reconciliation work;
-   - current effective parallelism if work is active;
-   - recommended next action.
-4. Never scan the whole repository just to report status.
-5. Never silently reclaim another execution's in-progress work.
-6. Repair purely mechanical state inconsistencies only when the correct state is provable from canonical artifacts; otherwise surface the exact inconsistency.

package/templates/BACKLOG.yaml

@@ -1,15 +0,0 @@
-work_items: []
-
-# Work item example:
-# - id: W001
-#   sequence: 1
-#   kind: feature | technical | maintenance
-#   title: Example
-#   slug: example
-#   folder: 001F-example  # F=feature, T=technical, M=maintenance
-#   mvp: true
-#   priority: high
-#   status: pending | ready | in_progress | blocked | needs_reconciliation | done
-#   depends_on: []
-#   impacted_by: []
-#   execution_id: null

package/templates/DECISIONS.yaml

@@ -1,18 +0,0 @@
-decisions: []
-
-# Consequential decisions only.
-# Lifecycle: candidate -> pending_user -> accepted -> superseded | rejected
-# Recommended fields:
-# - id
-# - kind: product | technical
-# - scope: global | work_item
-# - subject
-# - status
-# - context
-# - options
-# - recommendation
-# - choice
-# - rationale
-# - depends_on
-# - affects
-# - superseded_by

package/templates/ENGINEERING.md

@@ -1,35 +0,0 @@
-# Engineering Definition
-
-## Overview
-
-_To be defined by `flow-new` from product requirements, production constraints, existing code, and approved technical decisions._
-
-## Production Environment & Constraints
-
-## Architecture
-
-## Project Structure & Boundaries
-
-## Data & Persistence
-
-## Integration & Communication Patterns
-
-## Infrastructure & Deployment
-
-## Security & Privacy Baseline
-
-## Observability & Operations
-
-## Testing Strategy
-
-## Engineering Principles
-
-## Naming & Code Conventions
-
-Record only conventions that are worth making explicit. Infer trivial ecosystem conventions when a clear language/framework/repository standard exists.
-
-## Documentation Standards
-
-## Quality Gates
-
-## Sources

package/templates/PRD.md

@@ -1,23 +0,0 @@
-# Product Definition
-
-## Overview
-
-_To be defined by `flow-new`._
-
-## Problem
-
-## Target Users
-
-## Product Principles
-
-## MVP Outcome
-
-## MVP Scope
-
-## Post-MVP Scope
-
-## Global Product Constraints
-
-## Non-Goals
-
-## Sources

package/templates/STATE.yaml

@@ -1,11 +0,0 @@
-stage: initialized
-active_work_items: []
-pending_decisions: []
-last_completed_work_item: null
-recommended_action: flow-new
-
-execution:
-  current_run_id: null
-  effective_parallelism:
-    work_items: 0
-    tasks: {}

package/templates/SUMMARY.md

@@ -1,29 +0,0 @@
-# Project Overview
-
-## What We Are Building
-
-_Not defined yet._
-
-## MVP
-
-_Not defined yet._
-
-## Key Product Decisions
-
-_None yet._
-
-## Key Engineering Decisions
-
-_None yet._
-
-## Production Model
-
-_Not defined yet._
-
-## Quality Model
-
-_Not defined yet._
-
-## Current Progress
-
-Project discovery has not been completed.

package/templates/TASKS.yaml

@@ -1,13 +0,0 @@
-tasks: []
-
-# Task example:
-# - id: T001
-#   title: Example
-#   status: pending | ready | in_progress | blocked | done
-#   depends_on: []
-#   affected_areas: []
-#   acceptance: []
-#   decision_refs: []
-#   gate_refs: []
-#   execution_id: null
-#   commit: null

package/templates/WORK_ITEM_SPEC.md

@@ -1,29 +0,0 @@
-# Work Item
-
-## Overview
-
-Concise explanation of what this work item changes and why it exists. On completion, update this section to describe what was actually delivered.
-
-## Goal
-
-## Scope
-
-## Non-Goals
-
-## Product Decisions
-
-## Engineering Decisions
-
-## Requirements
-
-## Acceptance Criteria
-
-## Dependencies & Impact
-
-## Validation Gates
-
-## Validation Result
-
-## Delivery Notes
-
-Keep this concise. Git history carries implementation history; do not duplicate it here.

package/templates/config.yaml

@@ -1,29 +0,0 @@
-schema_version: 1
-framework_version: 0.2.0
-
-workflow:
-  autonomous_until:
-    - consequential_decision
-    - external_approval
-    - unrecoverable_blocker
-    - no_ready_work
-  continue_across_work_items: true
-
-parallelism:
-  strategy: maximum_safe
-  max_concurrent_work_items: auto
-  max_concurrent_tasks_per_work_item: auto
-  delegation: allowed
-
-execution:
-  primary_orchestrator: true
-
-commands:
-  test: null
-  lint: null
-  typecheck: null
-  build: null
-
-updates:
-  check_on_run: true
-  auto_update: false

package/templates/gates/README.md

@@ -1,19 +0,0 @@
-# Quality Gates
-
-This directory contains reusable project-wide validation gates created or refined during project discovery and work-item planning.
-
-A gate should be concise, readable, and actionable. Prefer deterministic command checks when tools can verify a rule reliably; use agentic policy gates only when judgment is required.
-
-Suggested frontmatter:
-
-```yaml
----
-id: architecture-boundaries
-kind: agentic # agentic | command
-blocking: true
-applies_when:
-  - architecture_changed
----
-```
-
-A gate may be introduced during a work item. If it establishes a reusable project-wide rule, treat that as a consequential technical decision and obtain developer approval before promoting it to this directory.