feat: source FFCA conventions from VGV Engineering - #4
Merged
Merged
Conversation
The canonical FFCA documentation moved from Notion to VGV Engineering,
where it is now split across seven pages and has picked up new material.
Every page on engineering.verygood.ventures serves a clean Markdown twin
at the same path with a .md extension, so references/ffca/ is now a byte
mirror of upstream rather than a hand-maintained paraphrase.
sync_reference.dart fetches it, --check reports drift, and a scheduled
workflow runs that check weekly. It is scheduled rather than a PR gate so
an upstream edit cannot fail an unrelated contributor's build.
Content the skills now teach, following upstream:
- Command and Query replace "use case" for the classes in use_cases/.
The folder keeps its conventional name; the classes do not.
- Presentation-only features, a _presentation package with no domain or
data sibling, composing other features' domains into a screen.
- Deferred loading: a package the app loads deferred must not also be
reachable eagerly, and the failure is silent.
- Widget slots as visual extension points, the conditions on sharing a
widget across features, and where a shared widget should live.
- Split routing tables must be part of one library or go_router_builder
drops the routes without failing the build.
- Converter classes for DTO mapping, and Provider as the module standard.
Dropped with upstream: Actions and Intents, Makefile, Non-Goals, Open
Discussions.
The layer policy itself is unchanged, so validate_layers.dart needs no
new rules. A presentation-only fixture locks that archetype into the test
suite. Skill citations now name a file and a section, and are qualified
with ${CLAUDE_PLUGIN_ROOT} so they resolve from the plugin rather than
the user's working directory.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SNHNDnPH7H7y2m4Pbsbmme
claude plugin validate warned that an unquoted ${CLAUDE_PLUGIN_ROOT}
splits into several words when the install path contains a space.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ
The two slash commands were shown in a single bash block, which reads as something to paste at once. Inside a Claude Code session the second only works after the first completes, so present them as separate steps and add the terminal one-liner, matching the sibling plugin READMEs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ
The FFCA section root returns 404 upstream. The overview page is the landing URL. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ
Contributor
ryzizub
reviewed
Sep 29, 2026
The mirror in references/ffca/ is what the model should read. A live URL invites it to fetch the page instead, which adds noise and can drift from the pinned copy. The READMEs keep the link for humans. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Vxxv9fVFGupLXEnmx5bSq
The validator only followed `path:` dependencies. In a Dart workspace, which the FFCA docs recommend, members depend on each other by name (`cart_domain: any`) with no path, so the validator saw no edges and passed every layer violation. It now resolves a dependency without a path to the workspace package of that name. Both fixtures are now real pub workspaces with `resolution: workspace`, each keeping one `path:` edge so both forms stay covered. The auditor and skills no longer describe dependencies as path-only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Vxxv9fVFGupLXEnmx5bSq
…-vgv-engineering # Conflicts: # README.md
…-vgv-engineering Resolves the skill frontmatter conflicts with #16 by keeping its single merged description and applying this branch's vocabulary: Commands and Queries instead of use cases, presentation-only features, widget slots, and routing table splits with deferred loading. Also points AGENTS.md and CONTRIBUTING.md, added in #13 and #14, at the references/ffca/ mirror and the working sync script instead of the Notion single-file reference this branch removes, and drops their leftover when_to_use guidance. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Vxxv9fVFGupLXEnmx5bSq
Open
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
2 participants
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.
Summary
The canonical FFCA documentation moved from Notion to VGV Engineering, where it is split across seven pages and has picked up new material. Every page there serves a clean Markdown twin at the same path with a
.mdextension, soreferences/ffca/is now a byte mirror of upstream rather than a hand-maintained paraphrase.scripts/sync_reference.dartfetches the mirror, and--checkreports drift.reference driftworkflow runs that check. It is scheduled rather than a PR gate so an upstream edit cannot fail an unrelated contributor's build.${CLAUDE_PLUGIN_ROOT}so they resolve from the plugin rather than the user's working directory.${CLAUDE_PLUGIN_ROOT}, clearing the lastclaude plugin validatewarning.What the skills now teach, following upstream
use_cases/. The folder keeps its name, the classes do not._presentationpackage with no domain or data sibling, composing other features' domains into a screen.go_router_builderdrops the routes without failing the build.Dropped with upstream: Actions and Intents, Makefile, Non-Goals, Open Discussions.
The layer policy itself is unchanged, so
validate_layers.dartneeds no new rules. A presentation-only fixture locks that archetype into the test suite.Verification
dart analyze --fatal-infos,dart format, anddart test(25 tests) pass.claude plugin validate .passes with no warnings.dart run scripts/sync_reference.dart --checkreports the mirror is up to date.🤖 Generated with Claude Code
https://claude.ai/code/session_01X1XbE7ufv8YHpJLV4MTZGQ