diff --git a/.gitignore b/.gitignore index 9f21159a..f7432f39 100644 --- a/.gitignore +++ b/.gitignore @@ -41,9 +41,10 @@ artifacts/ # Local session artifacts (plans, handoffs, current session notes) .agents/ +.flow/ .handoffs/ HANDOFF.md # Local CI / dogfood logs and screenshots (per-session, never committed) -.ci-logs/ -docs/manual_hun/ +.ci-logs/ +docs/manual_hun/ diff --git a/PRPs/PRP-flow-pack-E1-foundation.md b/PRPs/PRP-flow-pack-E1-foundation.md new file mode 100644 index 00000000..8a343f9f --- /dev/null +++ b/PRPs/PRP-flow-pack-E1-foundation.md @@ -0,0 +1,258 @@ +name: "PRP — flow-pack E1 Foundation (tracked contract + /flow-prime + rule + local install)" +description: | + Foundation slice of the flow: command-suite integration. Lands the tracked durable + source-of-truth (docs/flow-pack/**) plus the first command (/flow-prime) and the + umbrella-issue rule as a regenerable local install under .claude/**. Blocks E2–E5. + + + +## Issue links +- Umbrella: **#368** — feat(repo): integrate flow-pack methodology as the flow: command suite +- This epic: **#369** — flow-pack E1 — foundation (minimal viable; BLOCKS E2–E5) +- Milestone: **#1 flow-pack-suite** · labels: `epic`, `flow` + +--- + +## Goal +Implement the **E1 foundation** of the `flow:` command suite: a tracked, durable methodology +contract and the first command, installed locally per the **durable-source split**. The end +state: a reviewer on a fresh clone can read `docs/flow-pack/**`, regenerate the local +`.claude/commands/flow/` install, and run `/flow-prime` to produce a current-workflow-map + +"you are here" snapshot written to `.flow/state.md`. + +**Deliverable:** 4 files + 1 documented recovery path (see Desired tree). No E2–E5. No GitHub +issue creation. No commit/push. + +## Why +- `.claude/` is gitignored (CLAUDE.md "Learnings"), so commands/rules placed only there are lost + on a fresh clone and cannot be the source of truth. E1 establishes the tracked `docs/flow-pack/**` + as durable, with `.claude/**` as a regenerable runtime install. +- E1 is the minimal viable slice that proves the loop and unblocks the parallel epics E2–E4. + +## What +A docs-first foundation: tracked contract + tracked command template → local install → working +`/flow-prime`. + +### Success Criteria +- [ ] Tracked `docs/flow-pack-methodology.md` exists (Mermaid pipeline + invariants + FLAI mapping + + portability manifest + a "Fresh-clone recovery" section). +- [ ] Tracked `docs/flow-pack/commands/flow-prime.md` exists (the canonical command template/spec). +- [ ] Local `.claude/commands/flow/flow-prime.md` present, byte-regenerable from the tracked template. +- [ ] Local `.claude/rules/umbrella-issue.md` present (durable narrative lives in the methodology doc). +- [ ] Fresh-clone recovery documented and verified: `cp docs/flow-pack/commands/*.md .claude/commands/flow/` + reproduces the local command(s). +- [ ] `/flow-prime` runs: delegates to `core_piv_loop:prime` (codebase) + gathers gh state + writes + `.flow/state.md`; output includes a current-workflow-map and a you-are-here snapshot. +- [ ] Every created artifact carries a provenance header linking to its KB source. +- [ ] `git check-ignore .claude/commands/flow/flow-prime.md` confirms the local copy is NOT tracked; + `git status` shows `docs/flow-pack/**` as the only NEW tracked additions. + +## All Needed Context + +### Documentation & References +```yaml +# MUST READ — the reverse-engineered methodology (already analyzed in Phases 0–2) +- file: .flow/state.md + why: the full Phase 0–5 decision record — chosen workflow, durable-source split, epic plan +- file: .flow/brainstorm-log.md + why: the V1→V2 dogfood, 5-dim scores, and the 3-subagent research findings E1 is built on + +- file: /home/w7-hector/_KB-BASE-BY-w7/JOB/DIA-FLOW/ai_engineering_mermaid_flow_pack/docs/flow-analysis/01-decomposition.md + why: umbrella 7-field contract + epic phase taxonomy (foundation/parallel/release) + hierarchy-as-data — the umbrella-issue.md rule is reverse-engineered from this +- file: /home/w7-hector/_KB-BASE-BY-w7/JOB/DIA-FLOW/ai_engineering_mermaid_flow_pack/docs/flow-analysis/03-continuation-discipline.md + why: baseline → V1 → 3 read-only agents → score → V2; /flow-prime captures the "baseline reality" step +- file: /home/w7-hector/_KB-BASE-BY-w7/JOB/DIA-FLOW/ai_engineering_mermaid_flow_pack/docs/flow-analysis/02-execution-pipeline.md + why: the issue→5-subtask pipeline = the existing issue-to-subtasks skill; flow: hands off, does not reimplement + +# PATTERNS TO MIRROR (house style — match exactly) +- file: .claude/commands/core_piv_loop/prime.md + why: /flow-prime DELEGATES to this for codebase priming; mirror its command structure + section style +- file: .claude/rules/commit-format.md + why: rule anatomy to mirror (Title → Purpose → Rules/tables → Examples → Before X checklist) +- file: .claude/rules/branch-naming.md + why: second rule-style reference; also dictates the branch name for this work +- file: .claude/commands/base_prp/prp-create.md + why: the hand-off target invoked per epic after /flow-epics + +# CONSTRAINTS +- file: CLAUDE.md + section: "Learnings" — ".claude/ is gitignored — skills, rules, and hooks are local-only" + critical: this is WHY the durable-source split exists; do not treat .claude/** as committed truth +- file: .gitignore + why: confirm /.claude and .claude are ignored; .flow/ is local working state (consider ignoring it too) +``` + +### Current Codebase tree (relevant slice) +```bash +.claude/ + commands/{base_cm,base_evals,base_prp,core_piv_loop,do,git-operations,prompts,validation}/ # NO flow/ yet + rules/{branch-naming,commit-format,output-formatting,product-vision,security-patterns,shadcn-ui,test-requirements,ui-design,versioning}.md # NO umbrella-issue.md yet +docs/ # tracked; NO flow-pack/ yet +.flow/ # working state (untracked): state.md, brainstorm-log.md +PRPs/ # this PRP lives here +``` + +### Desired Codebase tree (files to add + responsibility) +```bash +docs/ + flow-pack-methodology.md # TRACKED durable contract: Mermaid pipeline, invariants, FLAI mapping, portability manifest, fresh-clone recovery + flow-pack/ + commands/ + flow-prime.md # TRACKED canonical template/spec for /flow-prime (source of truth) +.claude/ + commands/flow/ + flow-prime.md # LOCAL install — regenerable byte-copy of the tracked template (gitignored, NOT durable) + rules/ + umbrella-issue.md # LOCAL rule — agent contract; durable narrative is in docs/flow-pack-methodology.md +``` + +### Known Gotchas & Quirks +```text +# CRITICAL: .claude/ is gitignored (/.claude and .claude in .gitignore). The local command + +# rule are NEVER the committed source. Durable truth = docs/flow-pack/**. Verify with: +# git check-ignore .claude/commands/flow/flow-prime.md (must print the path = ignored) +# CRITICAL: the local install must be a faithful regeneration of the tracked template, NOT a +# hand-edited divergent copy. If they drift, the tracked template wins. Recovery = cp. +# GOTCHA: commit-format.md requires every commit reference an open issue → commit against (#369); +# branch off dev per branch-naming.md, e.g. feat/flow-pack-e1-foundation. +# GOTCHA: /flow-prime must DELEGATE to core_piv_loop:prime for codebase priming (do NOT duplicate +# its git ls-files/tree/log logic) and ADD only the gh-state + you-are-here + .flow/state.md write. +# GOTCHA: .flow/ is local working state. Consider adding `.flow/` to .gitignore so it is not +# accidentally committed (optional task T6; respect the dirty worktree — do not stage uv.lock or +# docker-compose.lan.yml). +# SCOPE: do NOT create flow-analyze/brainstorm/umbrella/epics commands here — E1 ships /flow-prime +# only. /flow-analyze is permanently deferred (folded into prime/brainstorm). +# PROVENANCE: every file starts with an HTML-comment provenance header naming its KB source. +# NO new runtime deps, no agent-teams/tmux (research fan-out = plain read-only subagents). +``` + +## Implementation Blueprint + +### list of tasks (dependency order) +```yaml +Task 1 — CREATE docs/flow-pack-methodology.md (tracked source of truth): + - INCLUDE: a Mermaid diagram of the 4-command pipeline (see .flow/state.md "Chosen workflow") + - INCLUDE: invariants list (read-only-until-approval; hierarchy-as-data; exactly-3 research agents; + score bands >=40/36-39/<36; 7-field umbrella; foundation->parallel->release; every defer has a reason) + - INCLUDE: FLAI mapping table (which methodology stage = which flow: command / existing skill) + - INCLUDE: "Durable-source split" section (docs/flow-pack/** tracked vs .claude/** local install) + - INCLUDE: "Fresh-clone recovery" section with the exact cp command + - INCLUDE: "Portability manifest" — the named params to change to reuse in another repo + - HEADER: provenance comment -> flow-analysis/{01,02,03}.md + +Task 2 — CREATE docs/flow-pack/commands/flow-prime.md (tracked command template): + - MIRROR structure of: .claude/commands/core_piv_loop/prime.md (frontmatter? section headings, $ARGUMENTS) + - SPEC the /flow-prime behavior: (a) delegate to core_piv_loop:prime; (b) gather gh state + (gh issue list, milestones, releases, project); (c) emit current-workflow-map + you-are-here; + (d) write/append .flow/state.md; (e) print gate result + next command (/flow-analyze folded in or + /flow-brainstorm) per the self-guiding convention + - INCLUDE dry-run note + provenance header + +Task 3 — INSTALL .claude/commands/flow/flow-prime.md (local runtime copy): + - REGENERATE as a byte-copy of docs/flow-pack/commands/flow-prime.md (cp), so they never diverge + - VERIFY: diff docs/flow-pack/commands/flow-prime.md .claude/commands/flow/flow-prime.md == empty + +Task 4 — CREATE .claude/rules/umbrella-issue.md (local rule): + - MIRROR anatomy of: .claude/rules/commit-format.md + - CONTENT (from Phase 4 draft in .flow + 01-decomposition.md): when to create an umbrella; + 7-field body contract; epic shape + phase contract; hierarchy-as-data (gh api sub_issues, no native + gh cmd); labels+milestone; write discipline (dry-run/idempotent/approval-gated); the command + source-of-truth & install split + recovery; validation (run audit-rules-drift) + - HEADER: provenance + "durable copy: docs/flow-pack-methodology.md" + +Task 5 — DOCUMENT fresh-clone recovery (in Task 1 doc, verify here): + - The methodology doc's recovery section reproduces .claude/commands/flow/ from docs/flow-pack/commands/ + +Task 6 (OPTIONAL) — MODIFY .gitignore: + - ADD `.flow/` so local working state is not accidentally committed + - PRESERVE existing entries; do NOT touch uv.lock / docker-compose.lan.yml in the worktree +``` + +### Per-task notes +```text +# Task 2 — /flow-prime spec is a DELEGATION wrapper, not a reimplementation: +# "Run core_piv_loop:prime for codebase priming, THEN gather gh state, THEN synthesize the +# current-workflow-map + you-are-here, write .flow/state.md, and print the next-command pointer." +# Task 4 — the rule is the LOCAL agent contract; keep it short and point to docs/flow-pack-methodology.md +# for the full narrative (avoid duplicating, since the rule isn't committed). +``` + +### Integration Points +```yaml +DOCS (tracked): + - add: docs/flow-pack-methodology.md, docs/flow-pack/commands/flow-prime.md +CLAUDE (local, gitignored): + - add: .claude/commands/flow/flow-prime.md, .claude/rules/umbrella-issue.md +GITIGNORE (optional): + - add: ".flow/" +HAND-OFF: + - on E1 completion, E2–E4 each go to base_prp:prp-create (separate, later) +``` + +## Validation Loop + +### Level 1: File presence + durable-source split +```bash +# tracked source of truth exists +test -f docs/flow-pack-methodology.md && test -f docs/flow-pack/commands/flow-prime.md && echo "OK tracked" +# local install exists and is gitignored (NOT durable) +test -f .claude/commands/flow/flow-prime.md && test -f .claude/rules/umbrella-issue.md && echo "OK local" +git check-ignore .claude/commands/flow/flow-prime.md .claude/rules/umbrella-issue.md # both must print (ignored) +# local install == tracked template (no drift) +diff -q docs/flow-pack/commands/flow-prime.md .claude/commands/flow/flow-prime.md && echo "OK no drift" +# only docs/flow-pack/** are NEW tracked files (plus this PRP); .claude/** not staged +git status --short +``` + +### Level 2: Fresh-clone recovery reproduction +```bash +# simulate recovery: blow away the local install, regenerate from tracked template, confirm identical +rm -f .claude/commands/flow/flow-prime.md +cp docs/flow-pack/commands/*.md .claude/commands/flow/ +diff -q docs/flow-pack/commands/flow-prime.md .claude/commands/flow/flow-prime.md && echo "OK recovery reproduces local" +``` + +### Level 3: /flow-prime smoke +```bash +# In a Claude Code session, run the command and confirm it produces the two artifacts: +# - a current-workflow-map (existing commands/skills/rules/workflows) +# - a you-are-here snapshot (branch, version, open issues, gap) +# and writes or appends to `.flow/state.md`. Confirm it ends by printing the next-command pointer. +# (No automated assertion — this is an interactive command; verify the output sections exist.) +``` + +## Tests / checks required +- [ ] Level 1 file-presence + gitignore + no-drift checks all pass. +- [ ] Level 2 recovery reproduces the local install byte-for-byte. +- [ ] Level 3 `/flow-prime` produces both required output sections + writes `.flow/state.md`. +- [ ] `audit-rules-drift` skill run against the new `umbrella-issue.md` reports no drift from AGENTS.md/CLAUDE.md. +- [ ] Provenance header present in all 4 created files (`grep -l provenance` finds each). +- [ ] No standard repo gate is broken (markdown-only change → ruff/mypy/pyright/pytest unaffected; run them to confirm green if any tooling touches docs). + +## Final Validation Checklist +- [ ] All 4 files created + recovery path documented and verified. +- [ ] Durable-source split holds: `docs/flow-pack/**` tracked; `.claude/**` ignored + regenerable. +- [ ] `/flow-prime` runs and writes `.flow/state.md`. +- [ ] `umbrella-issue.md` mirrors house rule anatomy; `audit-rules-drift` clean. +- [ ] E2–E5 NOT implemented; no new GitHub issues created. +- [ ] Branch is `feat/flow-pack-e1-foundation` off `dev`; commit (when the user authorizes) references `(#369)`. +- [ ] No commit/push performed by this PRP execution unless explicitly requested; `uv.lock` + `docker-compose.lan.yml` left untouched. + +## Anti-Patterns to Avoid +- ❌ Treating `.claude/commands/flow/` as the source of truth (it's gitignored — use `docs/flow-pack/**`). +- ❌ Reimplementing codebase priming in `/flow-prime` instead of delegating to `core_piv_loop:prime`. +- ❌ Building flow-analyze/brainstorm/umbrella/epics here — E1 is `/flow-prime` only. +- ❌ Letting the local install drift from the tracked template. +- ❌ Creating GitHub issues, committing, or pushing as part of E1 implementation. +- ❌ Staging `uv.lock` / `docker-compose.lan.yml` (pre-existing dirty worktree — leave alone). + +--- + +## Confidence Score: 8/10 +One-pass likelihood is high: the methodology is fully reverse-engineered and dogfooded (`.flow/`), +all dependencies are confirmed, and the work is markdown-only (no runtime/type risk). −2 for the +two judgement-heavy authoring tasks (the `/flow-prime` delegation spec and the rule's fidelity to +house style) and the gitignore split, which a careless executor can get subtly wrong. diff --git a/docs/flow-pack-methodology.md b/docs/flow-pack-methodology.md new file mode 100644 index 00000000..4966c242 --- /dev/null +++ b/docs/flow-pack-methodology.md @@ -0,0 +1,270 @@ + + +# flow-pack methodology + +> Turn "what should we do next?" into a dependency-aware, parallel-friendly, release-gated +> GitHub hierarchy — one pipeline from baseline reality to executable epics ready for PRPs. + +## Pipeline overview + +```mermaid +flowchart LR + P["/flow-prime
baseline reality
writes .flow/state.md"] + B["/flow-brainstorm
V1 naive → critique
3 agents → score → V2"] + U["/flow-umbrella
umbrella issue #N
7-field body"] + E["/flow-epics
epic issues #M–N
phase-linked sub-issues"] + X["base_prp:prp-create
per epic
→ PRP → implementation"] + + P -->|"baseline + .flow/state.md"| B + B -->|"approved V2 ship list + defer"| U + U -->|"umbrella #N created"| E + E -->|"epics #M–N linked"| X +``` + +**Research fan-out inside `/flow-brainstorm`** (not shown above to keep diagram readable): after +the critique gate, exactly 3 read-only subagents run in parallel — Agent A (Known Issues), +Agent B (Best Practices), Agent C (Dependencies) — then synthesize into the score table. + +--- + +## Stage 1 — Plan + +### /flow-prime — baseline reality + +1. Delegates to `core_piv_loop:prime` for codebase priming (never re-implements it). +2. Gathers GitHub state: open issues, milestones, labels, open PRs, recent releases. +3. Maps the current workflow: `.claude/commands/`, `.claude/rules/`, `.github/workflows/`. +4. Synthesizes a **current-workflow-map** (installed commands, rules, CI workflows, hooks) and a + **you-are-here snapshot** (branch, version, open issues, milestone, flow-namespace gap). +5. Writes or updates `.flow/state.md` with both sections. +6. Prints gate result and next-command pointer: `→ Next: /flow-brainstorm`. + +### /flow-brainstorm — V1 → score → V2 + +1. Produces **V1** — a flat bullet list of 5–10 candidate items, from baseline alone, unscored, + labeled "V1" explicitly. +2. Applies the **critique gate**: tags each item with zero or more flags + `{assumption, scope-creep, no-evidence}`. Does not fix V1; labels it for research. +3. Spawns **exactly 3 read-only research subagents** in parallel: + + | Agent | Mandate | + |-------|---------| + | A — Known Issues | Open bugs, prior incidents relevant to V1 items | + | B — Best Practices | Current docs, SDK, framework changes | + | C — Dependencies | Upstream changes, blockers, API availability | + +4. **Scores** every V1 item on 5 dimensions (1–10 each, max 50): + + | Dimension | What it captures | + |-----------|-----------------| + | Value | Outcome impact for users / stakeholders | + | Risk | Probability of failure or rework | + | Readiness | Upstreams done; decisions made | + | Complexity | Size of the work chunk | + | Evidence | Grounding in research agent reports | + +5. Applies **score-band rule**: + - **≥ 40** → V2 ship list + - **< 36** → defer list (each item carries an explicit one-clause reason) + - **36–39** → negotiation zone; surfaces to human before any GitHub write + +6. Prints a `X/10` one-pass confidence score for the V2 ship list. +7. Waits for explicit human approval gate before any GitHub write. +8. Hands off to `/flow-umbrella`. + +--- + +## Stage 2 — Decompose + +### /flow-umbrella — umbrella issue + +1. Creates the umbrella GitHub issue with the **7-field body contract** (see § Umbrella contract). +2. Attaches labels `umbrella` + `flow` and the project milestone. +3. Dry-run echoes the issue body; waits for approval before writing. +4. Prints gate + next-command pointer: `→ Next: /flow-epics`. + +### /flow-epics — epic issues + +1. Creates N epic issues (one per V2 ship item), phase-annotated + (Foundation / Parallel after Foundation / Release gate). +2. Links each epic as a sub-issue of the umbrella via the REST API + (`gh api repos/{owner}/{repo}/issues/{umbrella_id}/sub_issues -X POST -F sub_issue_id={epic_id}`). + No native `gh` sub-issue command — always `gh api` directly. +3. Dry-run echo + idempotent check + ~1 s rate-delay per write (GitHub API courtesy). +4. Hands off to `base_prp:prp-create` per epic. + +--- + +## Stage 3 — Execute (delegated) + +> Execution is fully handled by existing tools. The flow: suite stops at epic creation. + +| Epic-level work | Tool | +|-----------------|------| +| Write a PRP for the epic | `base_prp:prp-create` | +| Execute the PRP | `base_prp:prp-execute` | +| Decompose an epic into 5 subtasks | `issue-to-subtasks` skill | +| Session continuity across contexts | `writing-session-handoffs` / `HANDOFF.md` | +| Validate rule adherence | `audit-rules-drift` skill | + +--- + +## Invariants + +Every flow: command and every agent enforce these; violations must be flagged, not silently +bypassed: + +1. **Read-only until approval.** No GitHub write (issue create, label, sub-issue link) before an + explicit human "approve." Dry-run echo always precedes write. +2. **Hierarchy as data.** Every parent/child link is materialized via the REST sub-issue endpoint, + not just mentioned in body text. Closure rolls up natively; project board grouping is automatic. +3. **Exactly 3 research agents.** /flow-brainstorm always spawns Known Issues + Best Practices + + Dependencies. Never fewer (shallow research); never more (bloated). Additional domain agents are + allowed on top when a critique flag demands a specialist, but the 3 baseline mandates stay. +4. **Score bands are hard.** ≥ 40 ships, < 36 defers (with written reason), 36–39 goes to human. + No item ships without a complete 5-dimension row. +5. **7-field umbrella.** Every umbrella issue body must contain all 7 sections (Summary, Approach, + Decomposition, Out of scope, Success criteria, Risks, Tracking). Missing fields = not done. +6. **Foundation → Parallel → Release gate.** Exactly one Foundation epic (blocks all); N parallel + epics (feed release); exactly one Release-gate epic (closes only after Foundation + Parallel). +7. **Every defer has a reason.** A defer item with no written reason is a process failure. +8. **V1 is transient.** V1, the 3 agent reports, and the score table are working-state artifacts + (`.flow/`). Only V2 (the umbrella body) and the defer list survive as durable records. + +--- + +## Umbrella contract (7-field body) + +Required sections in every umbrella issue body (verified against live umbrella `#55` in +`w7-mgfcode/w7-base`, the reference project): + +| Field | Content | +|-------|---------| +| **Summary** | What's wrong with the current state, one paragraph | +| **Approach** | The architectural delta, one paragraph (no router / zero new runtime deps / etc.) | +| **Decomposition** | Bulleted epic list with `#N` refs + phase markers (Foundation / Parallel / Release gate) | +| **Out of scope (explicit)** | Items NOT closing this umbrella; each has a `#N` ref or a one-sentence reason it isn't tracked | +| **Success criteria** | Checkbox list (`- [ ]`) an outside reviewer can use as the close-or-not decision | +| **Risks** | Table with one mitigation per row | +| **Tracking** | Links to the project board, plan file, source-of-truth contract, and a `X/10` one-pass confidence score | + +--- + +## Epic contract + +Each epic issue body must contain: + +- Opening blockquote: `Sub-issue of #N (umbrella: )` + phase declaration + (`Foundation — blocks epics #M, #M+1 …` / `Parallel after Foundation` / `Release gate`). +- `## Purpose` — what this delivery surface gives the user. +- `## Sub-tasks` — bulleted list with `#N` references to child sub-issues. +- Labels ⊇ umbrella label set (plus the `epic` label). + +--- + +## Hierarchy-as-data (REST API) + +```bash +# Link an epic under the umbrella +gh api repos/{owner}/{repo}/issues/{umbrella_id}/sub_issues \ + -X POST -F sub_issue_id={epic_id} \ + --header "GitHub-Next-Preview: true" + +# Read sub-issues (GraphQL) +gh api graphql -f query=' + { repository(owner:"{owner}", name:"{repo}") { + issue(number: {umbrella_id}) { + subIssues(first: 20) { nodes { number title state } } + } + } }' +``` + +There is **no native `gh` sub-issue command** (cli/cli#10298). Always use `gh api` directly. +No GitHub CLI extension required. + +--- + +## FLAI mapping table + +Mapping from flow-pack methodology stages to ForecastLabAI-specific commands, skills, and tools. + +| Methodology stage (KB source) | flow: command | Delegated to / reuses | +|-------------------------------|---------------|----------------------| +| Baseline reality (03) | `/flow-prime` | `core_piv_loop:prime` (codebase), `gh` CLI (GitHub state) | +| V1 naive plan (03) | `/flow-brainstorm` | — (authored by Claude from baseline) | +| 3 read-only research agents (03) | `/flow-brainstorm` | plain subagents via Agent tool | +| Score + rerank (03) | `/flow-brainstorm` | — (5-dim table, bands ≥40/<36) | +| Human V2 approval (03) | `/flow-brainstorm` | — (explicit gate before GitHub write) | +| Umbrella issue creation (01) | `/flow-umbrella` | `gh issue create` | +| Epic creation + linking (01) | `/flow-epics` | `gh issue create` + `gh api` sub-issues | +| Sub-issue decomposition (02) | — (delegate) | `issue-to-subtasks` skill | +| PRP creation per epic | — (delegate) | `base_prp:prp-create` | +| PRP execution | — (delegate) | `base_prp:prp-execute` | +| Session continuity | `/flow-prime` | `writing-session-handoffs`, `HANDOFF.md` | +| Rules audit | `/flow-prime` | `audit-rules-drift` | + +--- + +## Durable-source split + +`.claude/` is gitignored in ForecastLabAI (see `CLAUDE.md` → Learnings). Any file placed only +in `.claude/` is lost on a fresh clone and cannot be the source of truth. + +| Layer | Location | Committed? | Purpose | +|-------|----------|------------|---------| +| Durable contract | `docs/flow-pack-methodology.md` | ✅ tracked | Narrative, invariants, API contract | +| Durable command templates | `docs/flow-pack/commands/*.md` | ✅ tracked | Source of truth for each command | +| Local runtime install | `.claude/commands/flow/*.md` | ❌ gitignored | Used by Claude Code slash-commands | +| Local agent rule | `.claude/rules/umbrella-issue.md` | ❌ gitignored | Agent contract during a session | + +**Invariant:** the local install is a faithful byte-copy of the tracked template. If they drift, +the tracked template wins. Recovery = `cp` (see § Fresh-clone recovery). + +--- + +## Fresh-clone recovery + +After a fresh clone (or after `.claude/` is wiped), regenerate the local install from the tracked +source: + +```bash +# Regenerate command(s) from tracked templates +mkdir -p .claude/commands/flow +cp docs/flow-pack/commands/*.md .claude/commands/flow/ + +# Verify no drift +diff docs/flow-pack/commands/flow-prime.md .claude/commands/flow/flow-prime.md \ + && echo "OK — no drift" + +# The umbrella-issue.md rule has no tracked template file (the durable content lives +# in this methodology doc, § Umbrella contract). Write a fresh copy from that section +# to .claude/rules/umbrella-issue.md when needed. +``` + +--- + +## Portability manifest + +To reuse the flow: suite in another repository, change these named parameters: + +| Parameter | ForecastLabAI value | What to change | +|-----------|--------------------|--------------------| +| `owner/repo` | `w7-mgfcode/ForecastLabAI` | Your GitHub org/repo | +| PRP hand-off command | `base_prp:prp-create` | Your equivalent PRP/issue command | +| Codebase prime command | `core_piv_loop:prime` | Your codebase prime command or equivalent | +| Label set | `umbrella`, `epic`, `flow` | Must be created in the target repo first | +| Command namespace | `flow` (`.claude/commands/flow/`) | Any namespace not already in use | +| Docs root | `docs/flow-pack/` | Wherever you track command templates | +| Working state dir | `.flow/` | Any local-only dir added to `.gitignore` | +| Milestone name | project-specific | Your target project's milestone | + +Nothing in the flow-pack commands is ForecastLabAI-specific except the `owner/repo` value and the +references to `base_prp:prp-create` and `core_piv_loop:prime`. Swap those two and it runs +anywhere. diff --git a/docs/flow-pack/commands/flow-prime.md b/docs/flow-pack/commands/flow-prime.md new file mode 100644 index 00000000..579aff41 --- /dev/null +++ b/docs/flow-pack/commands/flow-prime.md @@ -0,0 +1,172 @@ +--- +description: Capture baseline reality — delegate to core_piv_loop:prime, gather GitHub state, write .flow/state.md +--- + +<!-- provenance: flow-pack methodology stage 1 (continuation-discipline baseline step). + Source of truth: docs/flow-pack/commands/flow-prime.md (tracked). + Local install: .claude/commands/flow/flow-prime.md (gitignored, regenerable from this file). + Recovery: cp docs/flow-pack/commands/flow-prime.md .claude/commands/flow/flow-prime.md + Full methodology: docs/flow-pack-methodology.md --> + +# flow-prime: Baseline Reality Capture + +## Objective + +Capture the five baseline categories (repo state, docs, rules, issues, current state) needed to +plan a feature initiative. Produces two artifacts: + +1. **Current-workflow-map** — inventory of installed commands, rules, CI workflows, hooks, and + available skills. +2. **You-are-here snapshot** — branch, version, open issues, milestones, label gap, and a plain + "what's missing for the flow: suite" summary. + +Both artifacts are written to `.flow/state.md` (created if absent; phase sections updated if +present). The command ends by printing the gate result and the next-command pointer. + +**DELEGATION: do NOT re-implement codebase priming.** +Run the `core_piv_loop:prime` skill for all codebase reading. This command adds only the GitHub +state gathering, workflow mapping, and `.flow/state.md` writing on top of it. + +## Process + +### 1. Codebase priming (delegate) + +Run the `core_piv_loop:prime` skill. Let it produce the full project overview — purpose, +architecture, tech stack, core principles, and current state. Do not repeat that work here. + +Supplement with: + +!`git log -5 --oneline` + +!`git status --short` + +### 2. GitHub state + +Gather the five GitHub categories: + +!`gh issue list --state open --limit 20 --json number,title,labels --jq '.[] | "#\(.number): \(.title) [\(.labels | map(.name) | join(","))]"'` + +!`gh milestone list --json number,title,state --jq '.[] | "#\(.number) \(.title) (\(.state))"'` + +!`gh label list --json name --jq '[.[].name] | sort | join(", ")'` + +!`gh pr list --state open --json number,title,headRefName --jq '.[] | "#\(.number): \(.title) → \(.headRefName)"'` + +!`gh release list --limit 3 --json tagName,isPrerelease --jq '.[] | "\(.tagName)\(if .isPrerelease then " [pre]" else "" end)"'` + +### 3. Workflow map + +Inventory the installed flow: tooling without reading individual file contents. + +!`ls .claude/commands/ 2>/dev/null && echo "---" && ls .claude/rules/ 2>/dev/null && echo "---" && ls .github/workflows/ 2>/dev/null` + +!`ls .claude/commands/flow/ 2>/dev/null || echo "(no flow/ namespace yet)"` + +!`ls .claude/hooks/ 2>/dev/null || echo "(no hooks dir)"` + +Record: +- **Commands** — list of namespace dirs + top-level `.md` files under `.claude/commands/`. Note + whether a `flow/` namespace exists. +- **Rules** — list of `.md` files under `.claude/rules/`. Note whether `umbrella-issue.md` exists. +- **Workflows** — list of `.github/workflows/*.yml` files. +- **Hooks** — files in `.claude/hooks/`. +- **Skills** — list the user-invocable skills visible in your context (from the system prompt or + CLAUDE.md). Note reuse candidates for the flow: suite. + +### 4. Synthesize and write .flow/state.md + +Produce the two required sections: + +**Current-workflow-map** (what exists today): +- Commands: `<namespace-dir>` → `[file1.md, file2.md, …]`; top-level `.md` files listed +- Rules: `[file1.md, …]`; highlight `umbrella-issue.md` if present +- Workflows: `[ci.yml, cd-release.yml, …]` +- Hooks: `[hook-file, …]` +- Skills (reuse candidates): `[skill-name: purpose, …]` +- flow/ namespace: ✅ installed / ❌ missing + +**You-are-here snapshot** (current state): +- Branch: `<branch>` | Version: `<version from .release-please-manifest.json or CHANGELOG>` +- In-progress issues: `[#N title, …]` +- Active milestone: `<name>` or none +- Labels: umbrella=`[✅/❌]` epic=`[✅/❌]` flow=`[✅/❌]` +- Gap: concise plain-language statement of what the flow: suite still needs in this repo + +Write these two sections to `.flow/state.md` using **HTML marker pairs** so the update is +deterministic and never corrupts unrelated content: + +``` +<!-- FLOW-PRIME:CURRENT-WORKFLOW-MAP:START --> +## Current workflow map +<content> +<!-- FLOW-PRIME:CURRENT-WORKFLOW-MAP:END --> + +<!-- FLOW-PRIME:YOU-ARE-HERE:START --> +## You are here +<content> +<!-- FLOW-PRIME:YOU-ARE-HERE:END --> +``` + +Update rules: +- **File does not exist** — create it with a provenance HTML comment at the top, then write both + marker blocks (with their `## ` headings inside). +- **File exists, markers present** — replace only the content between each `START` / `END` pair; + leave every byte outside the markers unchanged. +- **File exists, markers absent** — append both marker blocks at the end of the file; do not + rewrite or delete any existing content. + +Never match on bare `##` headings to locate sections — the markers are the authoritative delimiters. + +### 5. Gate and next-command + +Print the gate result using the output format below, then the next-command pointer. + +Gate is ✅ **BASELINE CAPTURED** when all five categories are present: +- repo state (branch, recent commits, git status) +- docs (CLAUDE.md / AGENTS.md / README read) +- rules (`.claude/rules/` inventory) +- issues (open issues listed) +- current state (version, active milestone, label set) + +Gate is ❌ **INCOMPLETE** if any category is missing or uncertain — list what's missing and why +before printing the next-command pointer (still print it so the user knows where to go next). + +## Output Format + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 🗺️ flow-prime: Baseline Reality +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +📋 Codebase (core_piv_loop:prime) + [project overview summary from the delegated skill] + +📋 GitHub State + Open issues: N | Open PRs: M + Milestones: <name or none> + Labels: umbrella=[✅/❌] epic=[✅/❌] flow=[✅/❌] + Recent release: <tag> + +📋 Workflow Map + Commands: [namespaces / top-level files] + Rules: [files] umbrella-issue.md=[✅/❌] + Workflows: [files] + flow/ namespace: [✅/❌] + +📋 You Are Here + Branch: <branch> | Version: <version> + In-progress: [#N title, …] + Gap: <plain-language description of what's missing> + +──────────────────────────────────────────── + [✅/❌] BASELINE CAPTURED → .flow/state.md updated +──────────────────────────────────────────── + +→ Next: /flow-brainstorm <initiative description> +``` + +## Arguments + +`$ARGUMENTS` — optional free-text initiative description passed through to the gate result and +the next-command pointer (e.g., `/flow-prime integrate flow-pack methodology`). If omitted, the +you-are-here snapshot stands on its own.