FLOWS.json

{
    "index": [
        "multi_prompt",
        "direct_answer",
        "documentation_edit",
        "implementation",
        "broad_refactor",
        "pipeline_upgrade",
        "review",
        "quality_diagnostics",
        "continue_command",
        "compile_command",
        "manual_mode"
    ],
    "content": {
        "multi_prompt": {
            "then": [
                "split into independent intents",
                "classify each intent through WORKFLOW.json",
                "execute in dependency order",
                "run check_task.py at the final verification boundary when files changed",
                "report one coherent result"
            ]
        },
        "direct_answer": {
            "then": [
                "load docs-tech/PIPELINE-BOOTSTRAP.json",
                "run context_tags.py when the prompt needs routed context",
                "run knowledge_select.py with derived tags when source rules are needed",
                "answer from loaded context",
                "state uncertainty or missing contract when relevant"
            ]
        },
        "documentation_edit": {
            "then": [
                "load DOCS.json index",
                "read target owner document with list_document_keys.py or read_document_item.py",
                "edit structured documents with insert_document_item.py, move_document_item.py, migrate_document_item.py, or insert_checked_document_list_item.py when their contract fits",
                "for JSON structural/order-only edits, use json_node_edit.py or the narrow JSON wrappers before any manual content patch",
                "run normalize_json_files.py after JSON edits",
                "subroutine:task_flow_audit",
                "run check_task.py at the final verification boundary"
            ]
        },
        "implementation": {
            "then": [
                "load WORKFLOW.json",
                "run knowledge_code_context.py before source-code reads or edits — REQUIRED to bring borrowed-before-invented, web-research-spike gate, lightweight-futureproof, production-grade defaults, DDD-ADIV-when-possible, readability-first, explicit-diagnosable-flow, and other engineering rules into context",
                "subroutine:research_named_mechanism_gate",
                "run project_design_context.py -ProjectRoot <project> when the project's PIPELINE-CONFIG.json declares code_design_required_reads (zone splits, namespace rules, lifecycle constraints, per-project conventions) — writes ignored/project_design_context_gate.json",
                "inspect SCRIPTS.json index before manual work",
                "edit scoped files",
                "subroutine:task_flow_audit",
                "run check_task.py at the final verification boundary — verifies both ignored/code_context_gate.json and ignored/project_design_context_gate.json are fresh for current HEAD when changed-code is detected"
            ]
        },
        "broad_refactor": {
            "then": [
                "confirm high-cost scope when not already confirmed",
                "create passes",
                "subroutine:grouped_fragmented_task_handoff",
                "run knowledge_code_context.py before source-code reads or edits",
                "subroutine:research_named_mechanism_gate",
                "edit in coherent slices",
                "update affected contracts",
                "subroutine:task_flow_audit",
                "run check_task.py after each intentional verification boundary",
                "run finalize_task_check_commit_push.py when commit and push are required"
            ]
        },
        "pipeline_upgrade": {
            "then": [
                "audit source state",
                "subroutine:grouped_fragmented_task_handoff",
                "migrate structured contracts to JSON",
                "port routing/index scripts",
                "generalize default code behavior",
                "add explicit project types",
                "run pipeline_bootstrap_index.py after routing or index changes",
                "run normalize_json_files.py after JSON contract changes",
                "run compile_pipeline_context.py after source instruction, template, pack, or compiled-context changes",
                "subroutine:task_flow_audit",
                "run finalize_task_check_commit_push.py"
            ]
        },
        "review": {
            "then": [
                "inspect diff or target files",
                "use list_document_keys.py or read_document_item.py for structured document reads",
                "lead with findings",
                "include verification gaps",
                "avoid unrelated rewrites"
            ]
        },
        "quality_diagnostics": {
            "then": [
                "run check_task.py -Audit for repository quality diagnostics",
                "run check_ai_compiled_context.py or compile_pipeline_context.py for compiled-context drift",
                "inspect failures",
                "fix repeatable tooling failures in the owning tool",
                "subroutine:task_flow_audit",
                "rerun the failing script"
            ]
        },
        "continue_command": {
            "then": [
                "load docs-tech/PIPELINE-BOOTSTRAP.json",
                "resolve the next active pass, task, or target from the current plan/backlog contract",
                "before executing, decide whether the task needs user clarification, missing information, product direction, or a choice between meaningful implementation variants",
                "if clarification is needed, ask the user and wait instead of guessing; if everything is clear, proceed through the most specific matching flow",
                "during execution, stop and ask the user when new ambiguity, missing information, product direction, or material risk appears"
            ]
        },
        "compile_command": {
            "then": [
                "run compile_pipeline_context.py",
                "report generated drift"
            ]
        },
        "manual_mode": {
            "then": [
                "state why no script applies",
                "keep edits scoped",
                "recommend a script if repetition is likely"
            ]
        }
    },
    "metadata": {
        "document": {
            "title": "Source Pipeline Flows",
            "type": "flow_index",
            "language": "en"
        },
        "subroutines": {
            "research_named_mechanism_gate": [
                "Before writing code, check whether the active plan already contains research and a named implementation mechanism for the touched scope; if yes, execute that plan.",
                "If no researched/named mechanism exists, classify the change: obvious small fix means proceed directly.",
                "If the change is a non-obvious feature, architecture, bug, performance, hitbox/runtime, or structural task, do research first.",
                "Run the required research using the loaded knowledge base, project profile, local philosophy, and project-specific rules as the source for what risks and lenses matter.",
                "Name the implementation mechanism before editing."
            ],
            "task_flow_audit": [
                "Near task closure, run or answer the artifact-based task-flow audit instead of relying on a prose-only completion claim.",
                "Always cite the context route: loaded FLOWS/WORKFLOW/DOCS/STATE/plan/context records that were relevant to the task.",
                "Always cite the selected flow and the steps/subroutines actually followed.",
                "Always cite closure evidence: changed files, verification commands, generated artifacts, and remaining risk.",
                "Always state whether the changelog was updated from actual shipped changes; if no changelog update was needed, give the reason.",
                "Always state whether any tool failed mechanically; when it did, fix the owning tool or input contract/spec before preserving a manual workaround.",
                "Always state which repo tools/scripts were used and which edits were manual.",
                "For complex or high-risk tasks, run a short adversarial review from the changelog append: ask what the changelog says changed, then check whether the diff really implements that claim and whether verification, plan/state, tool usage, or future-debt risk is missing.",
                "Use tools/repo/task_flow_audit.py when available to print the checklist and changelog-based complex review prompt."
            ],
            "grouped_fragmented_task_handoff": [
                "Before broad implementation, check whether the task exceeds the fragmentation trigger: roughly >1500 LOC required context, >3 substantial substeps, multiple ownership boundaries, migration scope, performance investigation, or multi-system bug scope.",
                "If the trigger is met, split the work into user-approved groups; each group has one coherent goal, acceptance condition, expected output, and stop/checkpoint before the next group.",
                "Inside an approved group, split work into bounded sub-tasks with narrow ownership, expected artifact, minimal required context, and verification target.",
                "Run sub-tasks inside the approved group automatically without waiting for another user continue unless an escalation condition appears.",
                "Between sub-tasks, minimize live context, reload project context by tier, read the group sub-plan and latest STATE/PLAN handoff, then execute the next sub-task.",
                "After each sub-task, write the handoff with grouped_task_handoff.py when available: inspected files, changed files, current hypothesis/decision state, unresolved risks, next files/commands, and verification status.",
                "Stop and ask the user when scope expands outside the group, product direction is needed, verification changes the plan, a destructive/external/expensive action is needed, or the handoff is incomplete."
            ]
        }
    }
}