feat: monorepo consolidation — forge pipeline, MACP protocol, framework plugin, profiles/guides/skills
Work packages completed: - WP1: packages/forge — pipeline runner, stage adapter, board tasks, brief classifier, persona loader with project-level overrides. 89 tests, 95.62% coverage. - WP2: packages/macp — credential resolver, gate runner, event emitter, protocol types. 65 tests, 96.24% coverage. Full Python-to-TS port preserving all behavior. - WP3: plugins/mosaic-framework — OC rails injection plugin (before_agent_start + subagent_spawning hooks for Mosaic contract enforcement). - WP4: profiles/ (domains, tech-stacks, workflows), guides/ (17 docs), skills/ (5 universal skills), forge pipeline assets (48 markdown files). Board deliberation: docs/reviews/consolidation-board-memo.md Brief: briefs/monorepo-consolidation.md Consolidates mosaic/stack (forge, MACP, bootstrap framework) into mosaic/mosaic-stack. 154 new tests total. Zero Python — all TypeScript/ESM.
This commit is contained in:
Mos (Agent)
102
packages/forge/pipeline/rails/debate-protocol.md
Normal file
102
packages/forge/pipeline/rails/debate-protocol.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Debate Protocol
|
||||
|
||||
## Structured Phases (replaces open-ended rounds)
|
||||
|
||||
Debates run in three explicit phases, not freeform back-and-forth.
|
||||
|
||||
### Phase 1: Independent Position Statements
|
||||
|
||||
- Each participant reads the input independently
|
||||
- Each produces a written position statement with reasoning
|
||||
- **No participant sees others' positions during this phase**
|
||||
- This prevents framing bias (the Architect doesn't set the frame for everyone else)
|
||||
- Output: N independent position statements
|
||||
|
||||
### Phase 2: Response & Challenge
|
||||
|
||||
- All position statements are shared simultaneously
|
||||
- Each participant responds to the others:
|
||||
- Specific agreements (with reasoning, not "sounds good")
|
||||
- Specific disagreements (with counter-reasoning)
|
||||
- Risks the others missed
|
||||
- **Min 2, Max 10 response rounds** (each round = full cycle where every participant speaks)
|
||||
- A "round" is defined as: every active participant has produced one response
|
||||
- Circular detection: the Gate Reviewer (not the state machine) reviews round summaries and can halt if arguments are repeating
|
||||
|
||||
### Phase 3: Synthesis
|
||||
|
||||
- One designated synthesizer (usually the Software Architect for Planning 1, the lead Language Specialist for Planning 2)
|
||||
- Produces the output document (ADR, implementation spec, etc.)
|
||||
- **Must include:**
|
||||
- Chosen approach with reasoning
|
||||
- Rejected alternatives with reasoning
|
||||
- All dissents (attributed to the dissenting role)
|
||||
- Risk register
|
||||
- Confidence level (HIGH / MEDIUM / LOW)
|
||||
- Other participants review the synthesis for accuracy
|
||||
- If a participant's dissent is misrepresented → one correction round
|
||||
|
||||
## Cross-Cutting Agents (present in EVERY debate)
|
||||
|
||||
Two agents participate in every debate at every level — Board, Planning 1, Planning 2, Planning 3:
|
||||
|
||||
- **Contrarian**: Deliberately argues the opposing position. Challenges assumptions. Finds failure modes. Prevents groupthink. If everyone agrees, the Contrarian's job is to explain why they shouldn't.
|
||||
- **Moonshot**: Pushes boundaries. Proposes the ambitious version. Connects to the bigger vision. Prevents mediocrity. Always presents two versions: the moonshot AND a pragmatic stepping stone.
|
||||
|
||||
These two create productive tension — the Contrarian pulls toward "are we sure?" while the Moonshot pulls toward "what if we aimed higher?" The domain experts sit in the middle, grounding both extremes in technical reality.
|
||||
|
||||
## Round Definition
|
||||
|
||||
A **round** = one full cycle where every active participant has spoken once.
|
||||
|
||||
- 4 participants = 4 messages = 1 round
|
||||
- This is explicit to prevent confusion about costs
|
||||
|
||||
## Round Limits
|
||||
|
||||
| Phase | Min | Max | Cost (N participants, mixed models) |
|
||||
| ------- | ---------------------- | ------------------------ | ----------------------------------- |
|
||||
| Phase 1 | 1 (each speaks once) | 1 | N calls |
|
||||
| Phase 2 | 2 rounds | 10 rounds | 2N - 10N calls |
|
||||
| Phase 3 | 1 (synthesis + review) | 2 (if correction needed) | N+1 - 2N calls |
|
||||
|
||||
### Example: Board (6 participants — CEO, CTO, CFO, COO, Contrarian, Moonshot)
|
||||
|
||||
| Phase | Min | Max |
|
||||
| --------- | ------------- | ------------- |
|
||||
| Phase 1 | 6 | 6 |
|
||||
| Phase 2 | 12 | 60 |
|
||||
| Phase 3 | 7 | 12 |
|
||||
| **Total** | **~25 calls** | **~78 calls** |
|
||||
|
||||
### Example: Planning 1 (4 generalists + 2 cross-cutting = 6)
|
||||
|
||||
Similar range. Planning 2 may have more specialists = higher N.
|
||||
|
||||
Still much tighter than the original 3-30 open rounds.
|
||||
|
||||
## Mandatory Behaviors
|
||||
|
||||
1. **State your position with reasoning.** "I think X because Y." Not "sounds good."
|
||||
2. **Challenge other positions.** Every participant must challenge at least one position in Phase 2.
|
||||
3. **Raise risks others missed.** If you see a problem — you MUST raise it.
|
||||
4. **Formally dissent if not convinced.** Dissents survive into the output document.
|
||||
5. **Don't capitulate to move forward.** Hold your position if you believe it's right.
|
||||
|
||||
## Prohibited Behaviors
|
||||
|
||||
1. **No rubber-stamping.** "Looks good to me" without reasoning is rejected.
|
||||
2. **No scope creep.** Stay within the brief's boundaries.
|
||||
3. **No implementation during planning.** Specs, not code.
|
||||
4. **No deferring to authority.** The Architect's opinion is not automatically correct.
|
||||
|
||||
## Circular Detection
|
||||
|
||||
The **Gate Reviewer** (AI, Sonnet) — NOT the mechanical state machine — reviews Phase 2 round summaries. If arguments are repeating with no new information for 2+ rounds, the Gate Reviewer can:
|
||||
|
||||
1. Halt debate and force Phase 3 synthesis with dissents recorded
|
||||
2. Escalate to human if the disagreement is fundamental
|
||||
|
||||
## Convergence
|
||||
|
||||
Any participant can request moving to Phase 3. The state machine polls all participants (structured yes/no). If 2/3 agree → proceed to Phase 3. Otherwise → continue Phase 2 (within max rounds).
|
||||
89
packages/forge/pipeline/rails/dynamic-composition.md
Normal file
89
packages/forge/pipeline/rails/dynamic-composition.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Dynamic Composition Rules
|
||||
|
||||
## Principle
|
||||
|
||||
Only relevant specialists participate. A Go Pro doesn't sit in on a TypeScript project.
|
||||
|
||||
## Cross-Cutting Agents — ALWAYS PRESENT
|
||||
|
||||
Contrarian + Moonshot participate in EVERY debate at EVERY level. No exceptions.
|
||||
They are the two extremes that push the boundaries of thinking.
|
||||
|
||||
## Board — ALWAYS STATIC
|
||||
|
||||
CEO, CTO, CFO, COO + Contrarian + Moonshot. Every brief. No exceptions.
|
||||
|
||||
## Planning 1 — Selected by Brief Analyzer (NOT the Board)
|
||||
|
||||
After Board approval, the Brief Analyzer (Sonnet) determines technical composition.
|
||||
|
||||
### Selection Heuristics
|
||||
|
||||
| Signal in Brief | Include |
|
||||
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| Any brief (always) | Software Architect |
|
||||
| Any brief (always) | Security Architect — security is cross-cutting; implicit requirements are the norm, not the exception |
|
||||
| Deploy, infrastructure, scaling, monitoring | Infrastructure Lead |
|
||||
| Database, data models, migrations, queries | Data Architect |
|
||||
| UI, frontend, user-facing changes | UX Strategist |
|
||||
|
||||
### Minimum Composition
|
||||
|
||||
Planning 1 always has at least: Software Architect + Security Architect + Contrarian + Moonshot.
|
||||
The Brief Analyzer adds others as needed.
|
||||
|
||||
## Planning 2 — Selected by Planning 1
|
||||
|
||||
The ADR specifies which specialists participate.
|
||||
|
||||
### Selection Heuristics
|
||||
|
||||
Parse the ADR for:
|
||||
|
||||
| Signal in ADR | Include |
|
||||
| ----------------------------------------- | ---------------- |
|
||||
| TypeScript / .ts files | TypeScript Pro |
|
||||
| JavaScript / .js / Node.js | JavaScript Pro |
|
||||
| Go / .go files | Go Pro |
|
||||
| Rust / .rs / Cargo | Rust Pro |
|
||||
| Solidity / .sol / EVM | Solidity Pro |
|
||||
| Python / .py | Python Pro |
|
||||
| SQL / Prisma / database queries | SQL Pro |
|
||||
| LangChain / RAG / embeddings / agents | LangChain/AI Pro |
|
||||
| NestJS / @nestjs | NestJS Expert |
|
||||
| React / JSX / components | React Specialist |
|
||||
| React Native / Expo | React Native Pro |
|
||||
| HTML / CSS / responsive | Web Design |
|
||||
| Design system / components / interactions | UX/UI Design |
|
||||
| Blockchain / DeFi / smart contracts | Blockchain/DeFi |
|
||||
| Docker / Compose / Swarm | Docker/Swarm |
|
||||
| CI / pipeline / Woodpecker | CI/CD |
|
||||
|
||||
## Planning 3 — ALWAYS FIXED
|
||||
|
||||
Task Distributor + Context Manager. Every brief.
|
||||
|
||||
## Planning 2 — ALWAYS includes Contrarian + Moonshot alongside selected specialists
|
||||
|
||||
## Planning 3 — ALWAYS FIXED
|
||||
|
||||
Task Distributor + Context Manager + Contrarian + Moonshot.
|
||||
|
||||
## Review — Selected by task language
|
||||
|
||||
Code Reviewer (always) + Security Auditor (always) + the Language Specialist that matches the task's primary language.
|
||||
(Contrarian and Moonshot do NOT participate in Review — that's evidence-based, not debate.)
|
||||
|
||||
If PR changes API endpoints → API Documentation Specialist also reviews.
|
||||
|
||||
## Documentation — Selected by change type
|
||||
|
||||
After Test passes, before Deploy:
|
||||
|
||||
| Signal | Include |
|
||||
| ------------------------------------------ | ---------------------------------- |
|
||||
| API endpoint changes | API Documentation Specialist |
|
||||
| New architecture, setup steps, or patterns | Developer Documentation Specialist |
|
||||
| User-facing feature changes | User Documentation Specialist |
|
||||
|
||||
Documentation completeness is enforced at the Deploy gate.
|
||||
40
packages/forge/pipeline/rails/worker-rails.md
Normal file
40
packages/forge/pipeline/rails/worker-rails.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Worker Rails
|
||||
|
||||
## Constraints for Coding Stage Workers
|
||||
|
||||
### MUST
|
||||
|
||||
- Work only on files listed in the context packet
|
||||
- Follow patterns specified in the implementation spec
|
||||
- Use git worktree at `~/src/<repo>-worktrees/<task-slug>`
|
||||
- Push to a feature branch
|
||||
- Open a PR with description referencing the task ID
|
||||
- Run lint + typecheck + unit tests before declaring done
|
||||
- Self-check against acceptance criteria
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Make architectural decisions (those were made in Planning 1-2)
|
||||
- Refactor unrelated code
|
||||
- Edit files outside write scope
|
||||
- Introduce new dependencies without spec approval
|
||||
- Change API contracts without spec approval
|
||||
- Merge PRs (workers NEVER merge)
|
||||
- Skip tests defined in acceptance criteria
|
||||
- Work in main checkout or /tmp (always worktree)
|
||||
|
||||
### On Confusion
|
||||
|
||||
If the context packet is unclear or the spec seems wrong:
|
||||
|
||||
1. Do NOT guess and proceed
|
||||
2. Do NOT make your own architectural decisions
|
||||
3. STOP and report the ambiguity back to the orchestrator
|
||||
4. The orchestrator will route the question back to the appropriate planning stage
|
||||
|
||||
### On Completion
|
||||
|
||||
1. Push branch
|
||||
2. Open PR
|
||||
3. Report: task ID, branch name, acceptance criteria status
|
||||
4. EXIT — do not continue to other tasks
|
||||
Reference in New Issue
Block a user