Project Flood v0.2

Project Flood is a governed GitHub Copilot squad that can fan out into temporary research, review, or worktree-isolated build swarms. v0.2 turns the v0.1 operating contract into a portable Agent Plugins 1.0 package plus a repository-owned adapter.

The design stays intentionally bounded:

one human-facing Flood Squad Lead;
eight hidden specialists, including a dedicated Flood Integrator;
maximum three active workers per wave;
read-only research, architecture, verification, security, and swarm planning;
separate worktree sessions and exclusive paths for parallel editors;
deterministic hooks for dangerous commands, protected paths, ownership, and external writes;
independent verification before completion and after fan-in;
one Librarian for evidence-gated durable memory.

Project Flood does not train or modify a model. Its learning is reviewable repository context.

Install

Project Flood requires Python 3.10+ and the pinned validator dependency:

python -m pip install --requirement requirements.txt

Full repository install

Use this first. It copies the plugin capabilities and repository adapter into the target:

./scripts/install.sh --mode full /path/to/target-repository

pwsh ./scripts/install.ps1 -Mode full -TargetPath C:\src\target-repository

If the Project Flood plugin is already installed globally, disable it for a full-mode workspace; plugin and workspace hooks otherwise both run.

Plugin plus lightweight adapter

In VS Code, enable chat.plugins.enabled, run Chat: Install Plugin From Source, and enter https://github.com/Slight76/Project-Flood. Then install only the target-specific adapter:

./scripts/install.sh --mode adapter /path/to/target-repository

Adapter mode omits workspace copies of agents, skills, hooks, and hook code. The installed plugin supplies them; the repository keeps its contract, profile, routing, policy, setup workflow, canonical memory, runtime schema, and prompt wrappers.

Copilot CLI can install the same package directly with copilot plugin install Slight76/Project-Flood. For a cloud-agent adapter, review and merge .project-flood/copilot-settings.adapter.example.json into the target's existing .github/copilot/settings.json; do not overwrite existing settings.

Private repositories are supported when the current Git credentials can clone them. Review the plugin before trusting it because plugins may execute hooks.

Start

Open the configured target in a current VS Code release with Copilot enabled.
Run Chat: Open Customizations and verify Flood Squad Lead, the flood-* skills, and hooks are discovered.
Select Flood Squad Lead.
Ask it to use flood-repository-onboarding before implementation.
Review the proposed project profile, routing, harness capabilities, CODEOWNERS additions, and cloud-agent setup steps.
Start with a bounded read-only task, then a small verified implementation.

Prompt files such as flood-onboard are local VS Code shortcuts. Skills are the portable workflow authority.

What v0.2 adds

Area	v0.2 behavior
Packaging	Agent Plugins 1.0 plus full or adapter repository installation
Portability	Namespaced agents, portable tool aliases, skills replacing critical prompts, harness matrix
Enforcement	Workspace/plugin hooks with deny/ask/allow decisions and metadata-only audit
Build swarms	Validated task manifest, worktree sessions, wave/dependency/path rules, Integrator fan-in
Memory	Canonical Markdown body + YAML frontmatter; generated YAML index; ephemeral runtime JSON
Setup	Cloud-agent setup workflow and CODEOWNERS guidance
Lifecycle	Baseline-hash manifest, `diff`, `doctor`, `upgrade`, v0.1 `migrate`, recoverable `uninstall`
Quality	Real YAML parsing, Windows/Linux CI, pinned actions, threat model, adversarial eval corpus

See architecture, harness support, threat model, upgrades, and behavioral evaluations.

Release details are recorded in the changelog.

Hybrid memory

Durable knowledge lives in individual Markdown records under .agent-team/memory/:

the body holds decisions, reasoning, evidence, exceptions, examples, and consequences;
YAML frontmatter holds identity, type, lifecycle, owner, confidence, dates, scope, tags, sources, and optional permission/tool metadata;
memory-index.yaml is generated and contains no unique knowledge;
task authoring and hook audit data are gitignored JSON under .agent-team/runtime/, while activated worktree leases are shared transiently through Git's common directory;
only Flood Librarian promotes or supersedes canonical memory after evidence review.

Current code and enforced policy outrank memory. Rejected work never becomes active knowledge.

Validate and maintain

python scripts/sync_distribution.py --check
python scripts/flood.py validate --root . --distribution
python -m unittest discover -s tests -v

From an installed repository:

python .project-flood/flood.py validate --root .
python .project-flood/flood.py doctor --root .
python .project-flood/flood.py memory-index --root . --check

For an approved build swarm, validate and publish the shared worktree lease, then close it after verified fan-in:

python .project-flood/flood.py task-validate --root .
python .project-flood/flood.py task-activate --root .
python .project-flood/flood.py task-status --root .
python .project-flood/flood.py task-close --root . --status complete

Preview changes before upgrading:

python scripts/flood.py diff --target /path/to/target-repository
python scripts/flood.py upgrade --target /path/to/target-repository

Conflicts stop without modifying files. --force backs up conflicting files under the gitignored .project-flood/backups/ directory before replacement. Migration and uninstall are dry runs unless explicitly applied. See the lifecycle guide.

License

Limits

Hooks are preview defense-in-depth. They do not replace OS sandboxing, GitHub permissions, branch protection, required reviews, CI, or human approval. Tool and agent support varies by harness, and model behavior evaluations still need real harness runs. Project Flood bundles no MCP server and allowlists no external tool prefix by default.

slight76/project-flood