AGENTS.md git:20260929.6d2f986A

Immutable. This exact content never changes and is served at /api/v1/blob/33a801de1c6bbc0a.

# 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_architecture.md`, which is the single source of truth. It mirrors the canonical Notion page and is meant to be regenerated by `scripts/sync_reference.dart`. That script is still a stub, so the mirror is updated by hand from Notion for now. Never edit its content to match a skill. Change Notion, 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 (PostToolUse)
  validate_layers.sh       # Runs the validator on edited pubspec.yaml files
references/
  ffca_architecture.md     # Mirror of the Notion FFCA page, single source of truth
  code_templates/
    data_templates.md      # DTO, data source, mapper, repository implementation shapes
    domain_templates.md    # Model, repository interface, use case shapes
    presentation_templates.md  # Cubit, Module, route shapes
scripts/
  pubspec.yaml             # Dev dependency on package:test for the validator tests
  sync_reference.dart      # Regenerates references/ffca_architecture.md from Notion (stub)
  validate_layers.dart     # FFCA layer, naming, and cycle 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
      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, use cases, 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. One line on what the skill covers.
   - `when_to_use`: required here. The trigger phrases and situations that should activate the skill.
   - `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 name, for example `mcp__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_architecture.md` by section name, and into `references/code_templates/` for code shapes.

## Writing Conventions

- Do not restate architecture rules inside a skill. Cite the section of `references/ffca_architecture.md` 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 Notion first, then re-sync `references/ffca_architecture.md`. 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 `when_to_use`, 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 **Hook** 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 **Hook** section of `README.md` and the `## Hooks` section of `CLAUDE.md`.
- **An MCP tool is added, renamed, or removed.** Check every skill's `allowed-tools`. 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_architecture.md` are excluded from markdownlint.

## Commits

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

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