Membloc Multi-Agent Development Workflow

Goal: let multiple AI roles discuss, review, implement, verify, and push work without giving any single agent unsafe production authority.

1. Direction

Membloc should support a multi-agent development loop, but the loop should be PR-centered, not direct-to-main.

Recommended policy:

• AI agents may create branches and commits.
• AI agents may open pull requests.
• AI agents may comment on PRs with review findings.
• AI agents may update their own branches after review.
• AI agents must not push directly to main.
• AI agents must not create release tags that trigger production deployment without a human release gate.

This matches the current membloc-app-engine deployment shape: CI runs on main and PRs, while deploy runs on v*.*.* tag pushes. Tag creation is therefore a production-capable action and should stay outside autonomous agent authority.

2. Role model

Use role separation so the system has internal friction before code reaches production.

Role	Responsibility	Can edit code?	Can approve?	Can push?
Product Planner	turns request into scope, acceptance criteria, non-goals	no	no	no
Architect	checks system boundary, migration shape, data model, dependency impact	no by default	review only	no
Builder	implements a bounded slice on a feature branch	yes	no	branch only
Test Engineer	adds/updates tests and verification scripts	yes, test scope	no	branch only
Code Reviewer	reviews logic, maintainability, regressions, missing tests	no	review only	no
Security Reviewer	reviews auth, secrets, RBAC, data leakage, prompt/tool injection	no	review only	no
Release Verifier	checks CI, build, smoke, docs sync, rollback notes	no by default	release recommendation	no
Release Human	final merge/tag/deploy authority	yes	yes	main/tag

The important rule is that the Builder is never the only evaluator of its own work.

3. Workflow states

Request
  -> Triage
  -> Plan
  -> Architecture review
  -> Branch creation
  -> Implementation
  -> Test pass
  -> Code review
  -> Security review, if needed
  -> PR update loop
  -> Human merge
  -> Human release tag, if production deploy is intended
  -> Post-release proof note

Every transition should leave an artifact:

• plan markdown or issue body
• branch name
• commit SHA
• PR URL
• review comments
• test output summary
• CI run URL
• release proof note

4. Branch and commit rules

Branch naming:

agent/<area>/<short-task>

Examples:

agent/app-engine/ai-support-draft
agent/docs/ai-infra-plan
agent/portal/module-review-agent

Commit rules:

• Use small commits by concern.
• Follow the workspace Lore Commit Protocol.
• Record verification in Tested: and gaps in Not-tested:.
• Do not mix unrelated repos in one commit unless the task is explicitly cross-repo.

Example:

Add support-draft AI workflow boundary

The AI entrypoint starts as a draft-only operator tool so provider keys,
retrieval audit, and permission checks stay server-side before any
family-facing AI feature is exposed.

Constraint: Model credentials must never ship to Flutter or portal bundles
Rejected: Direct frontend model calls | cannot enforce family/publisher RBAC
Confidence: medium
Scope-risk: moderate
Tested: go test ./...
Not-tested: production provider latency

5. Repository authority boundaries

This workspace is a multi-repo folder, not one monorepo. Agents must treat each repo separately.

Repo	Agent write policy	Required verification before PR
membloc-app-engine	backend changes, migrations, AI gateway, APIs	go vet ./..., go build ./cmd/server, go test ./...
membloc-app	Flutter UI/client integration	flutter analyze, flutter test, relevant build/run smoke
membloc-developer-portal	publisher/admin AI review UI	npm run lint, npm run build
membloc-docs	published docs mirror and docs UI	npm run sync-docs, npm run build
membloc-sdk	public SDK bridge/API surface	SDK tests, hash/mirror checks when published
jmcunst-membloc-vault	playbooks, proof notes, records	content review, link consistency

When a task spans multiple repos, the Planner should split work into per-repo branches or clearly identify why one coordinated change is necessary.

6. Permission model

Use least privilege. The system needs separate credentials for separate actions.

Read-only agents

Can:

• read repo
• read docs
• read CI logs
• comment with findings

Cannot:

• push
• merge
• create tags
• change secrets
• run production commands

Branch-writing agents

Can:

• create branch
• push commits to branches matching agent/**
• open PRs
• update their own PR branches

Cannot:

• push to protected branches
• force-push shared branches
• approve their own PR
• create deployment tags
• change GitHub Actions secrets

Release agents

Initially should be recommendation-only.

Can:

• inspect CI
• summarize release readiness
• prepare release notes
• propose a tag name

Cannot:

• push release tags
• run SSH deploy
• rotate secrets
• apply production migrations

7. Review gates

At minimum:

• Builder creates or updates branch.
• Test Engineer verifies behavior.
• Code Reviewer reviews correctness and maintainability.
• Security Reviewer is required when changes touch auth, RBAC, storage, secrets, AI tools, prompt ingestion, or family/private data.
• Release Verifier checks CI and cross-repo docs impact.
• Human merges.

For low-risk docs-only changes, Code Reviewer and Test Engineer can collapse into one lightweight verification pass.

For production-impacting backend changes, keep all gates separate.

8. Multi-agent discussion format

Do not let agent discussion live only in chat. Store it as structured artifacts.

Recommended PR comment blocks:

## Planner Summary
- Scope:
- Non-goals:
- Acceptance criteria:
- Risk:

## Builder Notes
- Changed files:
- Key decisions:
- Tests run:
- Known gaps:

## Reviewer Findings
- Blocking:
- Non-blocking:
- Suggested follow-ups:

## Security Review
- Data classes touched:
- Auth/RBAC impact:
- Secret handling:
- Prompt/tool injection risk:

## Release Verification
- CI:
- Manual smoke:
- Docs sync:
- Rollback:

This makes the "discussion" durable and searchable by the future Brain.

9. AI infrastructure integration

The multi-agent development loop should reuse the AI infrastructure plan:

• Brain retrieves docs, playbooks, prior PRs, proof notes, and architecture records.
• Tracker stores tasks, PR state, review findings, and release evidence.
• Agents operate through a server-side AI Gateway.
• Every retrieval and tool execution gets audited.

Development agents should be treated as internal operators with scoped permissions, not as hidden superusers.

10. First implementation slice

Build this in stages.

Slice 1: Human-supervised agent PR loop

Scope:

• Define role prompts and PR comment templates.
• Add branch naming policy.
• Add CI requirement matrix per repo.
• Add proof-note template for AI-generated PRs.
• Keep all push/merge/release actions human-supervised.

Exit criteria:

• An AI can draft a plan, branch, commit, and PR for docs-only or low-risk code.
• Another AI can review the PR and produce findings.
• CI status is summarized before merge.
• Human still merges.

Slice 2: Branch-writing automation

Scope:

• Create a dedicated GitHub App or machine user.
• Restrict write access to branch patterns like agent/**.
• Require PR review and passing CI before merge.
• Block release tag creation from the agent token.

Exit criteria:

• Agent can push only to allowed branches.
• Branch protection blocks direct main writes.
• Audit logs show which agent made which commit.

Slice 3: Agent discussion memory

Scope:

• Ingest PR comments, review findings, CI summaries, release proofs, and rollback notes into Brain.
• Retrieve prior decisions during planning.
• Link every agent recommendation to source artifacts.

Exit criteria:

• New plans cite prior relevant decisions.
• Reviewers can detect repeated mistakes.
• Release verifier can find previous rollback notes.

Slice 4: Limited autonomous maintenance

Scope:

• Allow agents to autonomously open PRs for safe maintenance:
  • docs sync
  • dependency metadata review
  • generated SDK mirror checks
  • non-production lint fixes

Exit criteria:

• No production action is autonomous.
• Maintenance PRs remain small.
• Human can review and merge quickly.

11. Hard stops

Agents must stop and require human authority for:

• production deploy
• release tag push
• database migration on production
• secret rotation
• IAM/SSH/key changes
• family/private data export
• deleting data
• changing branch protection
• weakening CI or test gates

12. Recommended current policy

For Membloc now:

• Yes to multi-agent planning, implementation, review, and PR creation.
• Yes to agent branch push under agent/**.
• Yes to AI-generated review comments and release readiness summaries.
• No to direct main push.
• No to autonomous release tags.
• No to autonomous production deploy.

This gives the development speed benefits without turning production control into an unbounded agent action.