docs: add contributing, code of conduct, and security guides

.release-please-config.json

@@ -29,6 +29,7 @@
   "exclude-paths": [
     ".github",
     ".release-please-manifest.json",
-    ".release-please-config.json"
+    ".release-please-config.json",
+    "CONTRIBUTING.md"
   ]
 }

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,163 @@
+# 🦄 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. Open the project in your editor of choice. Any text editor works for skills and docs. The validator in `scripts/` needs the Dart SDK.
+
+## Types of Contributions
+
+| Contribution | Where |
+| ------------ | ----- |
+| **New skill** | `skills/<skill-name>/SKILL.md` |
+| **Improve an existing skill** | Edit the relevant `skills/*/SKILL.md` |
+| **Architecture conventions** | `references/ffca_architecture.md` |
+| **Layer validator** | `scripts/validate_layers.dart` and `scripts/test/` |
+| **Hook** | `hooks/` directory |
+| **Agent** | `agents/` directory |
+| **Bug reports & feature requests** | [GitHub Issues](https://github.com/VeryGoodOpenSource/vgv-ffca-plugin/issues) |
+
+## 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 does, in one sentence.
+when_to_use: When this skill should be triggered. Be specific.
+allowed-tools: Read Glob Grep
+---
+```
+
+| Field | Required | Rules |
+| ----- | -------- | ----- |
+| `name` | Yes | Lowercase letters, numbers, and hyphens only. Must match the skill's directory name. Prefix FFCA skills with `ffca-` |
+| `description` | Yes | What the skill covers |
+| `when_to_use` | Yes | The trigger phrases and scope. Self-scope to FFCA repos so the skill does not fire in a layered repo |
+| `allowed-tools` | No | Space-separated list of tools the skill may use |
+| `effort` | No | Reasoning effort hint, for example `high` for the audit skill |
+
+After the frontmatter, open with an H1 title and a one-line summary, then the workflow sections.
+
+### 2. Update `plugin.json` keywords
+
+Add relevant keywords to the `keywords` array in `.claude-plugin/plugin.json`.
+
+### 3. Update the README skills table
+
+Add a row to the skills table in `README.md` and to the list of slash commands below it. The skill name must link to the `SKILL.md` file:
+
+```markdown
+| [**Skill Name**](skills/<skill-name>/SKILL.md) | Short description of what the skill covers |
+```
+
+## Skill Writing Guidelines
+
+- **Point into the reference, do not restate it.** The conventions live in `references/ffca_architecture.md`. Link to the section by name so the architecture keeps one source of truth.
+- **Use clear directives.** No soft language like "consider" or "prefer". Say "Use X" or "Do not use Y".
+- **Fence all code blocks** with language identifiers, for example ` ```dart `.
+- **Reference packages by full name**, for example `package:go_router_builder`.
+- **Show anti-patterns alongside correct patterns** when it helps the reader see what to avoid.
+- **Keep skills short.** The current skills run well under 100 lines. Put workflow and judgement calls in the skill and leave the conventions to the reference.
+
+## Testing Locally
+
+Pushing straight to a PR only tells you the files are valid. Load your working copy into a real Claude Code session and exercise it before you commit.
+
+### Prerequisites
+
+- **Claude Code CLI** installed (`npm install -g @anthropic-ai/claude-code`).
+- **Dart SDK** and **jq** on your `PATH`. The hook needs both.
+- **Very Good CLI** (`dart pub global activate very_good_cli`) for the MCP server tools.
+
+### Load your local copy
+
+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. `${CLAUDE_PLUGIN_ROOT}` in `hooks/hooks.json` resolves to the directory you pass, so the hook script path resolves correctly.
+
+### Verify each component loaded
+
+| Component | How to verify |
+| --------- | ------------- |
+| **Skills** | Run `/help`. Skills appear namespaced as `/vgv-ffca-plugin:<skill>`, for example `/vgv-ffca-plugin:ffca-feature`. Invoke one to confirm it triggers |
+| **Hook** | In an FFCA repo, have Claude add a forbidden dependency to a `pubspec.yaml`, for example a `_data` package to a `_presentation` package. The edit must be blocked with the rule and the fix |
+| **Agent** | Run `/agents` and confirm `ffca-layer-auditor` is listed, or run `/vgv-ffca-plugin:ffca-audit` and confirm it dispatches the agent |
+| **MCP server** | Run `/mcp` and confirm `very_good_cli` shows connected |
+
+After editing a `SKILL.md`, an agent, or `.claude-plugin/plugin.json`, restart the session to pick up the change. Edits to `hooks/validate_layers.sh` take effect on the next matching tool call.
+
+### Run the validator tests
+
+The layer validator has its own test suite with fixture repos under `scripts/test/fixtures`:
+
+```bash
+cd scripts && dart pub get && dart test
+```
+
+Run the validator against a real FFCA workspace with:
+
+```bash
+dart run scripts/validate_layers.dart --all
+```
+
+### Validate before you push
+
+Run the same plugin check CI runs, from the repository root:
+
+```bash
+claude plugin validate .
+```
+
+This checks the manifest, skill frontmatter, hook JSON, MCP config, and file references. It is static, so it does not replace the live checks above.
+
+## CI Checks
+
+Every pull request runs the following checks from `.github/workflows/ci.yaml`:
+
+| Check | What it does | Config |
+| ----- | ------------ | ------ |
+| Markdown Quality | Lints all `*.md` files with markdownlint-cli2, except `CHANGELOG.md` and `references/ffca_architecture.md` | `config/custom.markdownlint.jsonc` |
+| Spelling Check | Runs cspell on all `*.md` files except `CHANGELOG.md` | `config/cspell.json` |
+| Layer Validator | Runs `dart analyze --fatal-infos`, `dart format --set-exit-if-changed`, and `dart test` in `scripts/` | `scripts/pubspec.yaml` |
+| Skills Lint | Validates every `SKILL.md` in `skills/` | Very Good Workflows `skills_lint` |
+| Plugin Validation | Validates the plugin | `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/) with the format:
+
+```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 routing callback example` |
+| `docs` | Documentation-only change | `docs: clarify hook prerequisites` |
+| `chore` | Maintenance and tooling | `chore: update cspell config` |
+| `refactor` | Restructure without changing behavior | `refactor: split validator rules` |
+| `ci` | CI pipeline changes | `ci: add validator format step` |
+
+PRs are squash-merged with the PR title as the commit message, and release-please builds the changelog from those titles. The **PR title must follow Conventional Commits**.
+
+## Pull Requests
+
+- Branch from `main`.
+- Use a Conventional Commits PR title, for example `feat: add ffca-testing skill`.
+- Keep PRs focused. Open **one skill per PR** for new skills.
+- 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
+
+The plugin ships skills, a hook, an agent, and a Dart validator script. The security-relevant surface areas are:
+
+### Skill, Agent, and Reference Files (`skills/*/SKILL.md`, `agents/*.md`, `references/`)
+
+- Insecure code examples that developers may copy into production
+- Outdated or misleading guidance
+- Recommendations that contradict current best practices
+
+### Hook and Validator Scripts (`hooks/`, `scripts/`)
+
+- Command injection vulnerabilities
+- Unsafe path handling
+- Unintended code execution
+
+### Plugin Manifest & 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,6 +3,7 @@
   "words": [
     "dtos",
     "ffca",
+    "frontmatter",
     "mappr",
     "mocktail",
     "operationalizes",