git:20261014.4b1ff47 to git:20261021.79ecd2a

3 added, 1 removed. Audit A to A.

# VGV FFCA Plugin

## Project Overview

VGV FFCA Plugin teaches Claude Code the Feature-First Clean Architecture (FFCA) for Flutter monorepos. It ships skills, one read-only auditor agent, and a PostToolUse hook that blocks pubspec edits breaking the layer rules.

The skills and the agent carry workflows only. The architecture itself lives in `references/ffca/`, which is the single source of truth. It is a byte mirror of the FFCA section of VGV Engineering, one file per page, regenerated by `scripts/sync_reference.dart`. Never edit its content to match a skill. Change the upstream page, re-sync, then fix the skills that drifted.

The only code is the Dart layer validator under `scripts/` and the bash hook wrapper that calls it.

## Repository Structure

```text

.mcp.json # MCP server configuration (Very Good CLI)

.claude-plugin/

plugin.json # Plugin manifest (name, version, description, keywords)

agents/

ffca-layer-auditor.md # Read-only architecture auditor subagent

config/

cspell.json # Spell check dictionary

custom.markdownlint.jsonc # markdownlint rules

hooks/

hooks.json # Hook definitions (PreToolUse, PostToolUse)

check_vgv_cli.sh # Checks the Very Good CLI version and auto-approves its MCP tools

check_vgv_cli_test.sh # Tests for check_vgv_cli.sh

validate_layers.sh # Runs the validator on edited pubspec.yaml files

validate_layers_test.sh # Tests for validate_layers.sh

references/

ffca/ # Byte mirror of the VGV Engineering FFCA pages, single source of truth

README.md # Manifest: which upstream page each file mirrors

overview.md # Goals, three-part structure, feature archetypes, layer model

domain.md # Models, Commands and Queries, repository interfaces, Summary pattern

data.md # Data sources, DTOs, converters and mappers

presentation.md # Modules, localizations, widget slots, subfeature barrels

navigation.md # Callback injection, typed routes, splitting the routing table

project_structure.md # Dependency rules, naming, folder layout, tooling

faq.md # Frequently asked questions

code_templates/

data_templates.md # DTO, data source, mapper, repository implementation shapes

domain_templates.md # Model, repository interface, Command and Query shapes

presentation_templates.md # Cubit, Module, route shapes

scripts/

+ analysis_options.yaml # Excludes the test fixtures from analysis

pubspec.yaml # Dev dependency on package:test for the validator tests

sync_reference.dart # Regenerates references/ffca/ from VGV Engineering, --check for drift

- validate_layers.dart # FFCA layer, naming, and cycle validator

+ validate_layers.dart # FFCA layer, naming, cycle, import, and barrel validator

test/

validate_layers_test.dart # Validator tests

fixtures/

valid_workspace/ # FFCA repo that must pass

invalid_workspace/ # One package per violation the validator must catch

+ warning_workspace/ # Warnings and suppressed errors only, must exit 0

not_ffca/ # Non-FFCA repo the validator must skip

skills/

ffca-architecture/SKILL.md # Orientation, layer rules, naming

ffca-audit/SKILL.md # Dispatches ffca-layer-auditor

ffca-cross-feature/SKILL.md # Summary pattern, Queries, widget slots, composing features

ffca-feature/SKILL.md # Scaffold and extend a feature

ffca-routing/SKILL.md # Callback injection, typed routes

```

## Skill File Format

Every `SKILL.md` follows this structure:

1. **YAML frontmatter** with these fields:

- `name`: required. Must match the skill's folder name exactly, lowercase letters, numbers, and hyphens only, prefixed `ffca-`.

- `description`: required. What the skill covers, when to use it, the trigger phrases that should activate it, and the deferral to `layered-architecture` for non-FFCA repos.

- `allowed-tools`: space-separated list of tools the skill may use, for example `Read Glob Grep`. Read-only skills stop there. Skills that write code add `Write Edit`, and MCP tools use their full plugin-scoped name, for example `mcp__plugin_vgv-ffca-plugin_very-good-cli__create`.

- `effort`: reasoning effort while the skill is active. Every skill here sets `high`.

2. **H1 title**, the human-readable skill name.

3. **A short purpose paragraph**, then numbered workflow steps.

4. **Citations** into `references/ffca/` by file and section name, and into `references/code_templates/` for code shapes.

## Writing Conventions

- Do not restate architecture rules inside a skill. Cite the file and section of `references/ffca/` by its heading so the reference stays the only place a rule is written.

- Frame standards as clear directives. No soft language like "consider" or "prefer".

- Use fenced code blocks with language identifiers for all examples.

- Reference packages by full name, for example `package:go_router_builder`.

- Use the FFCA package names consistently: `{feature}_domain`, `{feature}_data`, `{feature}_presentation`.

## Adding a New Skill

1. Create `skills/ffca-<name>/SKILL.md` following the format above.

2. Update `keywords` in `.claude-plugin/plugin.json` if the skill adds a new topic.

3. Add a row to the **Skills** table in `README.md`, linking the skill name to its `SKILL.md`.

4. Add the slash command to the list under the Skills table in `README.md`.

5. Add any new domain terms to the `words` list in `config/cspell.json`.

6. Update the repository structure in `AGENTS.md`.

## Adding a New Agent

Agents live in `agents/<name>.md` and are auto-discovered. No `plugin.json` change is needed. A file registers as `vgv-ffca-plugin:<name>`.

1. Create `agents/<name>.md` with YAML frontmatter:

- `name`: required. Must match the file name.

- `description`: required. When Claude should dispatch the agent, with `<examples>` blocks as in `ffca-layer-auditor.md`.

- `tools`: comma-separated bare tool names. A read-only agent omits `Edit` and `Write`.

- `model`: `inherit` to use the session model.

2. Add a row to the **Agent** table in `README.md`, linking the agent name to its file.

3. Add any new domain terms to the `words` list in `config/cspell.json`.

4. Update the repository structure in `AGENTS.md`.

## Maintaining Existing Skills, Hooks, and MCP Tools

Documentation drifts when an asset changes and the docs describing it do not. Update the matching docs in the same change:

- **The FFCA architecture changes.** Update the VGV Engineering page first, then run `dart run scripts/sync_reference.dart` to re-sync `references/ffca/`. Check every skill, the agent, and the code templates for section names that moved or rules that changed. If a dependency rule changed, update the rules table at the top of `scripts/validate_layers.dart` and its tests.

- **A skill's scope or triggers change.** Update `description` and the matching row in the `README.md` Skills table.

- **The validator's rules or flags change.** Update `scripts/test/validate_layers_test.dart` and its fixtures, the **Hooks** section of `README.md`, and the `## Hooks` section of `CLAUDE.md` if the hook's behavior changes.

- **A hook changes in `hooks/hooks.json`.** Update the **Hooks** section of `README.md` and the `## Hooks` section of `CLAUDE.md`. If it is `check_vgv_cli.sh` or `validate_layers.sh`, update its `_test.sh` file.

- **An MCP tool is added, renamed, or removed.** Check every skill's `allowed-tools` and the **MCP Integration** section of `README.md`. Nothing validates those names.

## Checks

CI runs markdownlint with `config/custom.markdownlint.jsonc`, cspell with `config/cspell.json`, the validator's analyze, format, and tests from `scripts/`, skills lint on `skills/`, and `claude plugin validate .`. `CHANGELOG.md` and `references/ffca/` are excluded from markdownlint. A weekly `reference_drift` workflow runs `sync_reference.dart --check` and fails when the mirror is stale.

## Commits

Use conventional commits: `type(scope): description`

Examples: `feat: add ffca-routing skill`, `fix(hooks): skip non-pubspec edits`, `docs: add AGENTS.md`