docs: add contributing guide, security policy, and code of conduct

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <tools@verygood.ventures>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+<https://www.contributor-covenant.org/faq/>

CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# 🦄 Contributing to VGV FFCA Plugin
+
+First of all, thank you for taking the time to contribute! 🎉👍 Before you do, please carefully read this guide.
+
+## Getting Started
+
+1. **Fork** the repository and clone your fork locally.
+2. Create a new branch from `main` for your work.
+3. Install the [Dart SDK](https://dart.dev/get-dart) and `jq` if you plan to touch the hook or the validator.
+
+## Types of Contributions
+
+| Contribution | Where |
+| ------------ | ----- |
+| **New skill** | `skills/<skill-name>/SKILL.md` |
+| **Improve an existing skill** | Edit the relevant `skills/*/SKILL.md` |
+| **Agent** | `agents/` directory |
+| **Hook** | `hooks/` directory |
+| **Validator rules** | `scripts/validate_layers.dart` and its tests in `scripts/test/` |
+| **Bug reports and feature requests** | [GitHub Issues](https://github.com/VeryGoodOpenSource/vgv-ffca-plugin/issues) |
+
+## The FFCA Reference
+
+`references/ffca_architecture.md` mirrors the canonical FFCA documentation. It is the single source of truth for the conventions, and the skills point into it by section name instead of restating it.
+
+- Do not edit the reference to change a convention. Propose the change upstream, then sync the mirror.
+- When a skill needs a convention, link to the relevant section of the reference. Do not copy the rule into the skill.
+
+## Adding a New Skill
+
+### 1. Create the skill file
+
+Create `skills/<skill-name>/SKILL.md`. The file must begin with YAML frontmatter:
+
+```yaml
+---
+name: <skill-name>
+description: "What the skill covers, in one sentence."
+when_to_use: Use when working in an FFCA monorepo and the user asks about X.
+---
+```
+
+| Field | Required | Rules |
+| ----- | -------- | ----- |
+| `name` | Yes | Lowercase letters, numbers, and hyphens only. Prefix FFCA skills with `ffca-` |
+| `description` | Yes | What the skill covers |
+| `when_to_use` | Yes | When the skill should trigger, scoped to FFCA repos so it does not fire in layered repos |
+| `allowed-tools` | No | Tools the skill may use without a permission prompt |
+
+### 2. Update the README skills table
+
+Add a row to the skills table and the direct-invocation list in `README.md`.
+
+### 3. Update `plugin.json` keywords
+
+Add relevant keywords to the `keywords` array in `.claude-plugin/plugin.json` when the skill covers new ground.
+
+## Skill Writing Guidelines
+
+- **Use clear directives.** Say "Use X" or "Do not use Y", not "consider" or "prefer".
+- **Fence all code blocks** with language identifiers, such as ` ```dart `.
+- **Provide complete, copy-pasteable snippets**, not fragments.
+- **Reference packages by full name**, such as `package:go_router`.
+- **Show anti-patterns alongside correct patterns** when it helps readers see what to avoid.
+- **Keep prose tight.** Every word in a SKILL.md consumes context the user needs for their actual work. Prefer decision tables to long if/else narratives, and keep to one sentence per rule.
+
+## Working on the Validator
+
+The validator lives in `scripts/` and imports only `dart:io`, so the hook runs with just the Dart SDK. The `pubspec.yaml` there exists only for the test suite.
+
+```bash
+cd scripts
+dart pub get
+dart analyze --fatal-infos
+dart format --output=none --set-exit-if-changed .
+dart test
+```
+
+Add a fixture under `scripts/test/fixtures/` for every new rule, covering both a passing and a failing workspace.
+
+## Testing Locally
+
+From the repository root, launch Claude Code pointed at this directory:
+
+```bash
+claude --plugin-dir .
+```
+
+`--plugin-dir` loads the plugin for that session only and overrides any marketplace-installed copy.
+
+| Component | How to verify |
+| --------- | ------------- |
+| **Skills** | Run `/help`. Skills appear namespaced as `/vgv-ffca-plugin:<skill>`. Invoke one to confirm it triggers. |
+| **Agent** | Ask Claude to audit an FFCA repo and confirm it dispatches `ffca-layer-auditor`. |
+| **Hook** | In an FFCA repo, have Claude add a forbidden dependency to a `pubspec.yaml` and confirm the edit is blocked. |
+
+Restart the session after editing a `SKILL.md`, `hooks/hooks.json`, or `.claude-plugin/plugin.json`.
+
+Before you push, run the same check CI runs:
+
+```bash
+claude plugin validate .
+```
+
+## CI Checks
+
+Every pull request runs the following checks automatically:
+
+| Check | What it does | Config |
+| ----- | ------------ | ------ |
+| Markdown lint | Lints all `*.md` files | `config/custom.markdownlint.jsonc` |
+| Spelling | Runs cspell on all `*.md` files | `config/cspell.json` |
+| Layer validator | Analyzes, formats, and tests the Dart validator | `scripts/` |
+| Skills lint | Validates every skill's frontmatter, structure, and links | VGV `skills_lint` reusable workflow |
+| Plugin validation | Validates the plugin manifest via Claude Code CLI | `claude plugin validate .` |
+
+If the spelling check flags a legitimate word, add it to the `words` array in `config/cspell.json`.
+
+## Commit Convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/). PRs are squash-merged with the PR title as the commit message, so the **PR title** must follow the format, since release-please builds the changelog from it:
+
+```text
+type(scope): description
+```
+
+| Type | When to use | Example |
+| ---- | ----------- | ------- |
+| `feat` | New skill or feature | `feat: add ffca-testing skill` |
+| `fix` | Fix an error or incorrect guidance | `fix: correct $extra hydration example` |
+| `docs` | Documentation-only change | `docs: clarify install steps` |
+| `chore` | Maintenance and tooling | `chore: update cspell config` |
+| `refactor` | Restructure without changing behavior | `refactor: split validator rules` |
+| `ci` | CI pipeline changes | `ci: cache Dart dependencies` |
+
+## Pull Requests
+
+- Branch from `main`.
+- Keep PRs focused, with one skill per PR for new skills.
+- Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
+- Ensure all CI checks pass before requesting review.
+- Link any related issues in the PR description.

SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+Only the latest release on `main` receives security updates.
+
+## Reporting a Vulnerability
+
+### GitHub Private Vulnerability Reporting (preferred)
+
+Report vulnerabilities through [GitHub's private vulnerability reporting](https://github.com/VeryGoodOpenSource/vgv-ffca-plugin/security/advisories/new).
+
+### Email
+
+Send an email to `tools@verygood.ventures` with a `[SECURITY]` subject prefix.
+
+### What to Include
+
+- A description of the vulnerability
+- Steps to reproduce the issue
+- Affected files or components
+
+### Response Timeline
+
+- **Acknowledgment**: within 5 business days
+- **Assessment**: within 10 business days
+- **Notification**: you will be notified when a fix is released
+
+## Scope
+
+VGV FFCA Plugin is a Claude Code plugin. Its only executable code is the validation hook and the Dart validator it runs. The security-relevant surface areas are:
+
+### Skill, Agent, and Reference Files (`skills/*/`, `agents/`, `references/`)
+
+- Insecure code examples that developers may copy into production
+- Outdated or misleading security guidance
+- Recommendations that contradict current best practices
+
+### Hook and Validator (`hooks/*.sh`, `scripts/*.dart`)
+
+- Command injection through file paths or hook payloads
+- Unsafe path handling or traversal outside the workspace
+- Unintended code execution
+
+### Plugin Manifest and MCP Config (`.claude-plugin/plugin.json`, `.mcp.json`)
+
+- Excessive permissions
+- Exploitable MCP server definitions
+
+## Recognition
+
+We are happy to acknowledge reporters in the fix PR upon request.

config/cspell.json

@@ -3,9 +3,11 @@
   "words": [
     "dtos",
     "ffca",
+    "frontmatter",
     "mappr",
     "mocktail",
     "operationalizes",
+    "pasteable",
     "posthog",
     "pubspec",
     "pubspecs",