AGENTS.md git:20261021.79ecd2aA

Immutable. This exact content never changes and is served at /api/v1/blob/230270abfb32fa4a.

# 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, 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`