feat(docs,repo): flow-pack E1 foundation — /flow-prime + tracked contract + rule (#369)#370
Merged
Merged
Conversation
Contributor
Reviewer's GuideIntroduces the foundational documentation and contracts for the new Sequence diagram for /flow-prime baseline capture processsequenceDiagram
actor User
participant flow_prime as flow-prime
participant core_piv_loop_prime as core_piv_loop:prime
participant gh_cli as gh_CLI
participant FS as Filesystem
User->>flow_prime: run /flow-prime $ARGUMENTS
flow_prime->>core_piv_loop_prime: core_piv_loop:prime
core_piv_loop_prime-->>flow_prime: project overview
flow_prime->>gh_cli: gh issue list / milestone list / label list / pr list / release list
gh_cli-->>flow_prime: GitHub state
flow_prime->>FS: ls .claude/commands/ .claude/rules/ .github/workflows/ .claude/hooks/
flow_prime->>FS: read .flow/state.md (if exists)
flow_prime->>FS: write updated .flow/state.md (workflow map + you-are-here)
flow_prime-->>User: baseline captured status + next command pointer (/flow-brainstorm)
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- In the
/flow-primespec, consider defining explicit delimiters (e.g., HTML comments or unique markers) around theCurrent-workflow-mapandYou-are-here snapshotsections in.flow/state.mdso that future implementations can reliably update those sections without relying on brittle##-header matching.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the `/flow-prime` spec, consider defining explicit delimiters (e.g., HTML comments or unique markers) around the `Current-workflow-map` and `You-are-here snapshot` sections in `.flow/state.md` so that future implementations can reliably update those sections without relying on brittle `##`-header matching.
## Individual Comments
### Comment 1
<location path="docs/flow-pack-methodology.md" line_range="119-122" />
<code_context>
+
+## Invariants
+
+Every flow: command and every agent enforces these; violations must be flagged, not silently
+bypassed:
+
</code_context>
<issue_to_address>
**issue (typo):** Use plural verb form here for correct subject–verb agreement.
Because the subject is plural ("Every flow: command and every agent"), the verb should be plural as well:
> Every flow: command and every agent enforce these; violations must be flagged, not silently bypassed:
```suggestion
## Invariants
Every flow: command and every agent enforce these; violations must be flagged, not silently
bypassed:
```
</issue_to_address>
### Comment 2
<location path="docs/flow-pack-methodology.md" line_range="90" />
<code_context>
+
+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 echos the issue body; waits for approval before writing.
+4. Prints gate + next-command pointer: `→ Next: /flow-epics`.
+
</code_context>
<issue_to_address>
**issue (typo):** Correct the spelling of "echos" to "echoes".
> Dry-run echoes the issue body; waits for approval before writing.
```suggestion
3. Dry-run echoes the issue body; waits for approval before writing.
```
</issue_to_address>
### Comment 3
<location path="PRPs/PRP-flow-pack-E1-foundation.md" line_range="221-224" />
<code_context>
+# 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/append .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.)
+```
</code_context>
<issue_to_address>
**suggestion (typo):** Clarify "writes/append" phrasing for grammatical correctness.
The phrase "writes/append .flow/state.md" is ungrammatical. Please rephrase, e.g.:
> and writes or appends to `.flow/state.md`.
This keeps the intent while reading more naturally.
```suggestion
# - 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.)
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+119
to
+122
| ## Invariants | ||
|
|
||
| Every flow: command and every agent enforces these; violations must be flagged, not silently | ||
| bypassed: |
Contributor
There was a problem hiding this comment.
issue (typo): Use plural verb form here for correct subject–verb agreement.
Because the subject is plural ("Every flow: command and every agent"), the verb should be plural as well:
Every flow: command and every agent enforce these; violations must be flagged, not silently bypassed:
Suggested change
| ## Invariants | |
| Every flow: command and every agent enforces these; violations must be flagged, not silently | |
| bypassed: | |
| ## Invariants | |
| Every flow: command and every agent enforce these; violations must be flagged, not silently | |
| bypassed: |
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Links
epic,flowWhat this PR does
Implements the E1 foundation of the
flow:command suite — the tracked durable source of truth and the first command (/flow-prime), installed locally per the durable-source split convention. No E2–E5 work was performed.Files committed (tracked — 4 files)
docs/flow-pack-methodology.mddocs/flow-pack/commands/flow-prime.md/flow-primecommand template (source of truth)PRPs/PRP-flow-pack-E1-foundation.md.gitignore.flow/to the local session artifacts sectionLocal install files — intentionally NOT committed
.claude/is gitignored in this repo (seeCLAUDE.md→ Learnings), so the following files were written to disk for the current session but are not tracked and do not appear in this PR:.claude/commands/flow/flow-prime.md— runtime install, byte-copy of the tracked template.claude/rules/umbrella-issue.md— local agent contractRecovery: on a fresh clone, run
cp docs/flow-pack/commands/*.md .claude/commands/flow/to regenerate the local install. Documented indocs/flow-pack-methodology.md§ Fresh-clone recovery.Durable-source split
docs/flow-pack/**.claude/commands/flow/*.md.claude/rules/umbrella-issue.mdValidation summary
.claude/**files confirmed gitignored;diff -qbetween tracked template and local install = emptycpfrom tracked template →diffemptyuv.lock/docker-compose.lan.ymlnever staged; no app/backend/frontend runtime code changedScope confirmation
app/backend code changedfrontend/code changedruff/mypy/pyright/pytestgates unaffectedSummary by Sourcery
Add the foundational documentation and specification for the new flow: command suite, including the /flow-prime command and durable-source split.
Enhancements:
Documentation: