Enhance public showcase for multi-agent lab

.gitattributes

@@ -0,0 +1,8 @@
+
+# Force explicit line-ending handling for these file types
+*.sh text eol=lf
+*.py text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.md text eol=lf
+.gitignore text eol=lf

.github/workflows/public-smoke.yml

@@ -0,0 +1,17 @@
+name: Public Smoke Test
+
+on:
+  push:
+    branches: [main, public-main, enhance-public-showcase]
+  pull_request:
+    branches: [main, public-main, enhance-public-showcase]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run public smoke test
+        run: bash tests/smoke_public.sh

.gitignore

@@ -1,31 +1,81 @@
-# secrets
+# =============================================================================
+# Multi Agent Lab — .gitignore
+# =============================================================================
+# These paths MUST NOT be committed — they contain runtime data, secrets,
+# or machine-specific paths. If you see any of these in a commit, remove them.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Runtime Logs & Memory (most critical)
+# -----------------------------------------------------------------------------
+**/logs/
+**/memory/daily/
+**/memory/failures/
+**/memory/decisions/
+**/workspace/
+**/*.log
+
+# -----------------------------------------------------------------------------
+# Environment & Secrets
+# -----------------------------------------------------------------------------
 .env
-.env.*
-*.key
+.env.local
+.env.*.local
 *.pem
-*.token
-credentials*
-secrets*
-
-# private local dirs
-.ssh/
-.aws/
-.azure/
-.claude/
-.codex/
-.openclaw/
-.config/
-
-# runtime generated files
-.multi-agent/logs/
-.multi-agent/memory/daily/
-.multi-agent/memory/failures/
-.multi-agent/memory/decisions/
-.multi-agent/workspace/*.txt
-
-# cache
-.cache/
-node_modules/
+*.key
+*.crt
+credentials/
+secrets/
+
+# -----------------------------------------------------------------------------
+# Private Runtime Directories
+# -----------------------------------------------------------------------------
+# These are home-directory configs and should never be copied into a repo
+**/.openclaw/
+**/.ssh/
+**/.aws/
+**/.claude/
+**/.codex/
+**/.config/
+**/.hermes/
+
+# -----------------------------------------------------------------------------
+# Python
+# -----------------------------------------------------------------------------
 __pycache__/
-*.log
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# -----------------------------------------------------------------------------
+# OS
+# -----------------------------------------------------------------------------
 .DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+
+# -----------------------------------------------------------------------------
+# Editor
+# -----------------------------------------------------------------------------
+.vscode/
+.idea/
+*.sublime-*
+
+# -----------------------------------------------------------------------------
+# Test / CI artifacts
+# -----------------------------------------------------------------------------
+coverage/
+htmlcov/
+.pytest_cache/
+
+# -----------------------------------------------------------------------------
+# Node (if any)
+# -----------------------------------------------------------------------------
+node_modules/
+package-lock.json
+yarn.lock

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to Multi Agent Lab
+
+## Adding a New Agent
+
+1. Create a new file in `.multi-agent/agents/your_agent.md`
+2. Follow the existing agent template format:
+
+```markdown
+# Your Agent Name
+
+## Responsibility
+One sentence on what this agent does.
+
+## Inputs
+What this agent reads (goals, findings, plans, etc.)
+
+## Outputs
+What this agent produces.
+
+## Safety Considerations
+Any specific safety concerns for this role.
+```
+
+3. Add the agent to the coordinator's agent list in `config.yaml`
+4. Add a corresponding workflow type in `.multi-agent/workflows/` if needed
+5. Update `docs/architecture.md` to document the new agent role
+6. Run `bash tests/smoke_public.sh` to verify structure
+
+## Adding a New Workflow
+
+1. Create a new file in `.multi-agent/workflows/your_workflow.yaml`
+2. Define which agents run and in what order:
+
+```yaml
+name: your_workflow
+agents:
+  - router
+  - scout
+  - analyst
+  - guard
+  - executor
+  - verifier
+stop_conditions:
+  - guard_denied
+  - verifier_failed
+```
+
+3. Update `docs/workflows.md` with the new workflow
+4. Add an example in `examples/` if applicable
+
+## Safety-First Contribution Rules
+
+- **Never commit secrets** — no API keys, tokens, passwords, or credentials
+- **Never commit runtime artifacts** — no `logs/`, `memory/daily/`, `memory/failures/`, `memory/decisions/`
+- **Workspace files only** — executor writes must stay in `.multi-agent/workspace/`
+- **Test before push** — run `bash tests/smoke_public.sh` before submitting a PR
+- **Describe what was implemented** — do not claim aspirational features as implemented
+
+## Before Opening a PR
+
+Run the full pre-push checklist:
+
+```bash
+# 1. Smoke test passes
+bash tests/smoke_public.sh
+
+# 2. No forbidden files in git status
+git status --short | grep -E 'logs|memory/daily|memory/failures|memory/decisions|workspace/.*\.txt|\.env'
+
+# 3. No accidental secrets
+grep -rInE 'api[_-]?key|token|secret|password|credential|BEGIN PRIVATE|sk-' \
+  --exclude-dir=.git \
+  --exclude="*.md" .
+
+# 4. All new scripts pass syntax checks
+bash -n new_script.sh
+python3 -m py_compile new_script.py
+```
+
+## Repository Hygiene
+
+This is a public repository. Assume everything you push is visible to the internet.
+
+- The `.gitignore` covers most secret patterns — extend it if you add new tools
+- Do not add `.env` files, `*.pem` keys, or credential caches
+- If you accidentally push a secret, treat it as compromised and rotate immediately
+- When in doubt, ask before pushing
+
+## Code of Conduct
+
+Be respectful and collaborative. This is an educational and experimental project.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qian-le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,138 @@
 # Multi Agent Lab
 
-A local multi-agent workflow skeleton built around OpenClaw, Hermes, and Claude Code.
+[![Public Smoke Test](https://github.com/qian-le/multi-agent-lab/actions/workflows/public-smoke.yml/badge.svg)](https://github.com/qian-le/multi-agent-lab/actions/workflows/public-smoke.yml)
 
-This repository contains:
-- Agent role prompts
-- Workflow definitions
-- Runtime scripts
-- Adapter documents
-- Memory templates
-- Safe executor and verifier logic
+A local multi-agent workflow skeleton demonstrating how to route tasks through specialized agents — Scout, Analyst, Hermes Reviewer, Guard, Executor, and Verifier — with a mandatory safety gate before any execution.
 
-Runtime logs, local memories, generated workspace files, and private tool configs are excluded from the public release.
+This is a **learning and experimentation skeleton**, not a production system. It runs entirely on a single machine and is designed to teach agent role separation, safety-first execution, and memory management.
+
+## Project Structure
+
+```
+multi_agent_lab/
+├── multi_agent/                 # Core skeleton code
+│   ├── agents/                # Agent role definitions
+│   ├── adapters/              # Backend adapter layer
+│   ├── workflows/             # Workflow type definitions
+│   ├── scripts/               # Shell/Python runner scripts
+│   ├── memory/templates/       # Structured memory templates
+│   └── config.yaml            # Workflow routing configuration
+├── docs/                      # Architecture, workflow, and integration docs
+├── examples/                  # Sanitized example runs (no real logs)
+├── tests/                    # Public smoke test
+├── templates/                # Example config templates
+│   └── .multi-agent/          # Example local config (no real secrets)
+├── .github/workflows/
+└── README.md
+```
+
+## Quick Start
+
+```bash
+# Check that all scripts have valid syntax
+bash tests/smoke_public.sh
+
+# Detect available backends
+bash multi_agent/scripts/detect_tools.sh
+
+# Dry-run an info workflow (read-only, never executes)
+bash multi_agent/scripts/run_workflow.sh --type info --goal "list all agent files"
+
+# Dry-run a modify workflow (stops at Guard)
+bash multi_agent/scripts/run_workflow.sh --type modify --goal "create a hello world file"
+```
+
+## Core Agent Roles
+
+| Agent | Responsibility |
+|---|---|
+| **Router** | Classifies incoming goal into workflow type |
+| **Scout** | Read-only inspection of workspace and memory |
+| **Analyst** | Plans approach and sub-steps |
+| **Hermes Reviewer** | Fallback reasoning for complex tasks |
+| **Guard** | Mandatory safety gate — blocks before Executor runs |
+| **Executor** | Runs actions via shell, Python, or Claude Code |
+| **Verifier** | Checks executor output matches the original intent |
+| **Memory Manager** | Reads/writes structured memory templates |
+
+## Safety Model
+
+- **Guard before Executor**: Every execution passes through Guard first
+- **Workspace-only writes**: Executor can only write to `multi_agent/workspace/`
+- **No secret logging**: API keys, tokens, and credentials are never written to memory or logs
+- **Deny list**: Commands like `sudo`, `rm -rf /`, recursive chmod/chown on system paths are blocked by default
+
+See [docs/security.md](docs/security.md) for the full threat model.
+
+## Environment Setup
+
+This project requires **no external services** to run the skeleton. The smoke test and dry-runs work out of the box.
+
+For real agent runtime calls (OpenClaw, Hermes, Claude Code), you need to set up your own backend:
+
+```bash
+# Required environment variables (copy templates and fill in your values)
+cp templates/env.example .env
+
+# Edit .env with your actual API keys and paths
+nano .env
+```
+
+See `templates/.multi-agent/config.yaml.example` for the full config template with field documentation.
+
+## What Cannot Be Committed
+
+The following are automatically excluded via `.gitignore`. If you see them in a commit, something is wrong:
+
+- `multi_agent/logs/` — runtime message logs
+- `multi_agent/memory/daily/` — session day logs
+- `multi_agent/memory/failures/` — failure records
+- `multi_agent/memory/decisions/` — decision logs
+- `multi_agent/workspace/` — executor output files
+- `.env` — contains real API keys and tokens
+- `~/.openclaw/`, `~/.ssh/`, `~/.aws/`, `~/.claude/` — private runtime dirs
+- `*.pyc`, `__pycache__/`, `*.pyo`
+- Any file containing real tokens, API keys, or secrets
+
+## Smoke Test
+
+```bash
+bash tests/smoke_public.sh
+```
+
+The smoke test checks:
+1. All required files exist
+2. All bash scripts have valid syntax
+3. All Python scripts compile without error
+4. Forbidden directories (logs, memory, workspace) are not tracked by git
+5. `.gitignore` covers all critical items
+6. README makes no inflated claims
+7. Integration docs clearly mark planned items as planned
+
+## Backend Adapters
+
+The skeleton ships with four backend adapters in `multi_agent/adapters/`:
+
+| Adapter | Backend | Status |
+|---|---|---|
+| `shell_adapter.md` | Direct `bash` / `python3` | Always available |
+| `openclaw_adapter.md` | OpenClaw agent dispatch | Requires OpenClaw runtime |
+| `hermes_adapter.md` | Hermes advisory review | Requires Hermes CLI |
+| `claude_code_adapter.md` | Claude Code session | Requires Claude Code |
+
+Each adapter documents how to configure the backend and what the call/response format looks like.
+
+## Model Integration Roadmap
+
+Planned integration targets for a long-context reasoning model (e.g. MiMo-V2.5-Pro):
+
+- **Analyst** — multi-step planning with long task history
+- **Verifier** — semantic output verification beyond diff/exit-code
+- **Hermes-style review** — contextual risk reasoning instead of pattern deny-lists
+- **Memory summarization** — condensing accumulated session records
+
+See [docs/model-integration-roadmap.md](docs/model-integration-roadmap.md) for the full plan. MiMo-V2.5-Pro integration is **planned**, not currently implemented.
+
+## License
+
+MIT