create-shhs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHHS Contributors
+
+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.

package/README.md

@@ -0,0 +1,301 @@
+# Self-Healing Hybrid Swarm (SHHS)
+
+**A reusable AI governance system for software engineering projects**
+
+SHHS is a structured multi-agent AI workflow that prevents architectural drift, controls technical debt, and enables safe AI-assisted development at scale.
+
+---
+
+## What is SHHS?
+
+SHHS organizes AI development through **role separation** and **contract-driven workflows**:
+
+- **Architecture is protected** through ADRs and governance rules
+- **Development is fast** with clear feature contracts
+- **Validation is objective** using independent review agents
+- **Technical debt is monitored** continuously
+
+Instead of one AI doing everything, SHHS mimics a mature engineering organization with distinct roles and responsibilities.
+
+---
+
+## Quick Start
+
+### Installation
+
+Install SHHS into any existing project:
+
+```bash
+# Method 1: NPX (fastest)
+npx create-shhs
+
+# Method 2: Git submodule (recommended for tracking updates)
+git submodule add https://github.com/your-org/shhs .shhs
+.shhs/scripts/install.sh
+
+# Method 3: Direct installation
+git clone https://github.com/your-org/shhs /tmp/shhs
+/tmp/shhs/scripts/install.sh .
+rm -rf /tmp/shhs
+```
+
+### What Gets Installed
+
+```
+your-project/
+├── .ai/
+│   ├── agents/              # AI role definitions
+│   ├── ADR/                 # Architectural Decision Records
+│   ├── contracts/           # Public interfaces
+│   ├── features/            # Cucumber feature contracts
+│   └── memory/              # Patterns and anti-patterns
+├── CLAUDE.md                # Governance rules
+├── ARCHITECTURE.md          # Architecture template
+└── README.ai.md             # Quick reference
+```
+
+### Next Steps
+
+1. **Read governance rules:** `cat CLAUDE.md`
+2. **Bootstrap architecture:** Load Root Architect from `.ai/agents/architect.md`
+3. **Create first feature:** Define contract in `.ai/features/`
+4. **Follow the pipeline:** Architect → Developer → Reviewer → QA → Approval
+
+Full setup guide: **[docs/setup.md](docs/setup.md)**
+
+---
+
+## Core Concepts
+
+### Role Separation
+
+Six specialized agents with strict boundaries:
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| **Root Architect** | [.ai/agents/architect.md](template/.ai/agents/architect.md) | Defines architecture, creates ADRs and feature contracts |
+| **Domain Architect** | [.ai/agents/domain-architect.md](template/.ai/agents/domain-architect.md) | Maintains bounded context consistency |
+| **Developer** | [.ai/agents/developer.md](template/.ai/agents/developer.md) | Implements features within defined boundaries |
+| **Static Reviewer** | [.ai/agents/static-reviewer.md](template/.ai/agents/static-reviewer.md) | Validates structural compliance |
+| **QA Validator** | [.ai/agents/qa.md](template/.ai/agents/qa.md) | Validates test results and coverage |
+| **Debt Observer** | [.ai/agents/debt-observer.md](template/.ai/agents/debt-observer.md) | Detects emerging technical debt |
+
+### Mandatory Pipeline
+
+Every feature follows this sequence:
+
+```
+┌─────────────────┐
+│ Root Architect  │ Creates feature contract
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Developer     │ Implements feature
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Static Reviewer │ Validates structure
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  QA Validator   │ Validates behavior
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│Domain Architect │ Approves merge
+└─────────────────┘
+```
+
+**No step may be skipped.**
+
+### Contract-Driven Development
+
+Features are defined as Cucumber `.feature` files before implementation:
+
+```gherkin
+# .ai/features/042-user-authentication.feature
+Feature: User Authentication
+
+  Scenario: User logs in with valid credentials
+    Given a registered user exists
+    When they submit valid credentials
+    Then they receive an auth token
+```
+
+Developer agents implement to satisfy contracts. QA agents validate against them.
+
+### Architectural Memory
+
+Decisions and patterns are preserved:
+
+- **ADRs** (`.ai/ADR/`) record architectural decisions
+- **Patterns** (`.ai/memory/patterns.md`) capture approved solutions
+- **Anti-patterns** (`.ai/memory/anti-patterns.md`) prevent known mistakes
+
+---
+
+## Example Workflow
+
+### Starting a New Feature
+
+```bash
+# 1. Load Root Architect
+cat .ai/agents/architect.md
+
+# 2. Architect creates contract
+# Output: .ai/features/042-payment-integration.feature
+
+# 3. Load Developer
+cat .ai/agents/developer.md
+
+# 4. Developer reads contract and implements
+# Developer follows patterns from .ai/memory/patterns.md
+
+# 5. Load Static Reviewer
+cat .ai/agents/static-reviewer.md
+
+# 6. Reviewer validates structure → PASS/FAIL
+
+# 7. Load QA Validator
+cat .ai/agents/qa.md
+
+# 8. QA runs tests → PASS/FAIL
+
+# 9. Load Domain Architect
+cat .ai/agents/domain-architect.md
+
+# 10. Domain Architect approves → APPROVED/REJECTED
+```
+
+### Making Architectural Changes
+
+```bash
+# 1. Create ADR via Root Architect
+# Output: .ai/ADR/007-adopt-event-sourcing.md
+
+# 2. Update ARCHITECTURE.md with new decision
+
+# 3. Update affected contracts in .ai/contracts/
+
+# 4. Implement changes via feature pipeline
+```
+
+---
+
+## Key Features
+
+### ✅ Prevents Architectural Drift
+
+- All structural changes require ADRs
+- Static Reviewer enforces layer boundaries
+- Domain Architects protect bounded contexts
+
+### ✅ Objective Validation
+
+- QA Validator checks measurable results (tests, coverage)
+- Static Reviewer validates structure independently
+- No single agent both implements and validates
+
+### ✅ Technical Debt Monitoring
+
+- Debt Observer analyzes codebase periodically
+- Generates reports in `.ai/debt/`
+- Proposes refactor contracts
+
+### ✅ Team Collaboration
+
+- Governance rules in version control
+- ADRs provide decision history
+- Contracts define clear expectations
+
+### ✅ Reusable Across Projects
+
+- Project-agnostic template
+- Easy installation via script
+- Customizable agent roles
+
+---
+
+## Documentation
+
+- **[Setup Guide](docs/setup.md)** — Complete installation and configuration guide
+- **[CLAUDE.md](template/CLAUDE.md)** — Governance rules (installed in projects)
+- **[ARCHITECTURE.md](template/ARCHITECTURE.md)** — Architecture template
+- **[Agent Roles](template/.ai/agents/)** — Definitions for all agents
+
+---
+
+## Requirements
+
+- **Bash** (for installation script)
+- **Git** (optional, for submodule method)
+- **AI assistant** (Claude, GPT, or compatible)
+
+Works with any tech stack — SHHS is language and framework agnostic.
+
+---
+
+## Philosophy
+
+### Why Multi-Agent?
+
+Single AI agents face conflicting incentives:
+
+- Fast delivery vs. architectural discipline
+- Shipping features vs. maintaining quality
+- Implementing vs. validating objectively
+
+SHHS separates these concerns into distinct roles with clear authority.
+
+### Why Contracts?
+
+Feature contracts create clear expectations:
+
+- Developers know what to build
+- QA knows what to validate
+- Architects define scope upfront
+
+This prevents scope creep and misalignment.
+
+### Why Governance?
+
+Long-lived projects accumulate decisions. Without governance:
+
+- Decisions are lost or forgotten
+- Patterns aren't reused
+- Anti-patterns repeat
+
+SHHS preserves institutional knowledge in `.ai/memory/`.
+
+---
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Open an issue first for discussion
+2. Follow existing agent role patterns
+3. Test installation script on sample projects
+4. Update documentation
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details
+
+---
+
+## Support
+
+- **Issues:** https://github.com/your-org/shhs/issues
+- **Discussions:** https://github.com/your-org/shhs/discussions
+- **Docs:** [docs/setup.md](docs/setup.md)
+
+---
+
+**Built for teams that want AI speed without sacrificing architectural discipline.**

package/bin/install.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  blue: '\x1b[34m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  bold: '\x1b[1m'
+};
+
+const c = (color, text) => `${colors[color]}${text}${colors.reset}`;
+
+// Parse arguments
+const args = process.argv.slice(2);
+const targetDir = args[0] || process.cwd();
+
+// Help flag
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+${c('blue', '╔════════════════════════════════════════════════════════╗')}
+${c('blue', '║  Self-Healing Hybrid Swarm — NPX Installer            ║')}
+${c('blue', '╚════════════════════════════════════════════════════════╝')}
+
+${c('bold', 'Usage:')}
+  npx create-shhs [directory]
+
+${c('bold', 'Arguments:')}
+  [directory]    Target directory (default: current directory)
+
+${c('bold', 'Examples:')}
+  npx create-shhs               # Install in current directory
+  npx create-shhs .             # Install in current directory
+  npx create-shhs /path/to/app  # Install in specific directory
+
+${c('bold', 'Options:')}
+  -h, --help     Show this help message
+
+${c('bold', 'What gets installed:')}
+  .ai/              AI governance structure
+  CLAUDE.md         Governance rules
+  ARCHITECTURE.md   Architecture template
+  README.ai.md      Quick reference guide
+
+${c('blue', 'Documentation:')} https://github.com/your-org/shhs
+`);
+  process.exit(0);
+}
+
+console.log(`
+${c('blue', '╔════════════════════════════════════════════════════════╗')}
+${c('blue', '║  Self-Healing Hybrid Swarm — Installation             ║')}
+${c('blue', '╚════════════════════════════════════════════════════════╝')}
+`);
+
+// Resolve target directory
+const target = path.resolve(targetDir);
+
+// Validate target exists
+if (!fs.existsSync(target)) {
+  console.log(`${c('red', '✗ Error:')} Target directory does not exist: ${target}`);
+  console.log(`${c('yellow', '  Tip:')} Create it first with: mkdir -p ${targetDir}`);
+  process.exit(1);
+}
+
+console.log(`${c('blue', 'Installing to:')} ${target}\n`);
+
+// Template source (in the NPM package)
+const templateDir = path.join(__dirname, '..', 'template');
+
+if (!fs.existsSync(templateDir)) {
+  console.log(`${c('red', '✗ Error:')} Template directory not found`);
+  console.log(`${c('yellow', '  This should not happen. Please report this issue.')}`);
+  process.exit(1);
+}
+
+// Helper: Copy file if it doesn't exist
+function copyIfMissing(src, dest, description) {
+  if (fs.existsSync(dest)) {
+    console.log(`${c('yellow', '⊙ Skipping')} ${description} (already exists)`);
+    return false;
+  }
+
+  fs.copyFileSync(src, dest);
+  console.log(`${c('green', '✓ Installed')} ${description}`);
+  return true;
+}
+
+// Helper: Copy directory recursively
+function copyDirRecursive(src, dest, description) {
+  if (fs.existsSync(dest)) {
+    console.log(`${c('yellow', '⊙ Skipping')} ${description} (already exists)`);
+    console.log(`${c('yellow', '  To update, remove')} '${dest}' ${c('yellow', 'and re-run installation')}`);
+    return false;
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, entry.name);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+
+  console.log(`${c('green', '✓ Installed')} ${description}`);
+  return true;
+}
+
+// Install .ai directory
+console.log(`${c('blue', '[1/3] Installing AI governance structure')}`);
+copyDirRecursive(
+  path.join(templateDir, '.ai'),
+  path.join(target, '.ai'),
+  '.ai directory'
+);
+console.log('');
+
+// Install governance files
+console.log(`${c('blue', '[2/3] Installing governance files')}`);
+copyIfMissing(
+  path.join(templateDir, 'CLAUDE.md'),
+  path.join(target, 'CLAUDE.md'),
+  'CLAUDE.md'
+);
+copyIfMissing(
+  path.join(templateDir, 'ARCHITECTURE.md'),
+  path.join(target, 'ARCHITECTURE.md'),
+  'ARCHITECTURE.md'
+);
+copyIfMissing(
+  path.join(templateDir, 'README.ai.md'),
+  path.join(target, 'README.ai.md'),
+  'README.ai.md'
+);
+console.log('');
+
+// Validate setup
+console.log(`${c('blue', '[3/3] Validating setup')}`);
+
+const gitignorePath = path.join(target, '.gitignore');
+if (fs.existsSync(gitignorePath)) {
+  const gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+  if (gitignoreContent.match(/^\.ai$/m)) {
+    console.log(`${c('yellow', '⚠ Warning:')} .ai directory is in .gitignore`);
+    console.log(`${c('yellow', '  Consider tracking .ai for team collaboration')}`);
+  } else {
+    console.log(`${c('green', '✓')} .gitignore configuration looks good`);
+  }
+} else {
+  console.log(`${c('yellow', '⊙')} No .gitignore found`);
+}
+
+// Check if git repo
+let isGitRepo = false;
+try {
+  execSync('git rev-parse --git-dir', { cwd: target, stdio: 'ignore' });
+  isGitRepo = true;
+} catch (e) {
+  // Not a git repo
+}
+
+if (!isGitRepo) {
+  console.log(`${c('yellow', '⊙')} Not a git repository`);
+  console.log(`${c('yellow', '  Consider initializing with:')} git init`);
+}
+
+console.log('');
+
+// Success message
+console.log(`${c('green', '╔════════════════════════════════════════════════════════╗')}`);
+console.log(`${c('green', '║  Installation Complete                                 ║')}`);
+console.log(`${c('green', '╚════════════════════════════════════════════════════════╝')}`);
+console.log('');
+
+console.log(`${c('blue', 'Next Steps:')}`);
+console.log('');
+console.log(`  1. Review ${c('green', 'CLAUDE.md')} to understand the governance model`);
+console.log(`  2. Update ${c('green', 'ARCHITECTURE.md')} with your system design`);
+console.log(`  3. Start by loading the ${c('green', 'Root Architect')} agent:`);
+console.log(`     ${c('yellow', 'cat .ai/agents/architect.md')}`);
+console.log(`  4. Bootstrap your architecture using the architect`);
+console.log('');
+
+console.log(`${c('blue', 'Documentation:')}`);
+console.log(`  • README.ai.md — Quick reference guide`);
+console.log(`  • .ai/agents/ — All agent role definitions`);
+console.log(`  • .ai/memory/ — Patterns and anti-patterns`);
+console.log('');
+
+if (isGitRepo) {
+  console.log(`${c('yellow', 'Pro tip:')} Commit the .ai directory to version control for team collaboration`);
+  console.log('');
+  console.log(`${c('blue', 'To commit:')}`);
+  console.log(`  ${c('yellow', 'git add .ai CLAUDE.md ARCHITECTURE.md README.ai.md')}`);
+  console.log(`  ${c('yellow', 'git commit -m "chore: add SHHS AI governance system"')}`);
+  console.log('');
+}
+
+console.log(`${c('blue', '📚 Full documentation:')} https://github.com/your-org/shhs`);
+console.log('');

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-shhs",
+  "version": "1.0.0",
+  "description": "Self-Healing Hybrid Swarm - AI governance system installer",
+  "main": "bin/install.js",
+  "bin": {
+    "create-shhs": "./bin/install.js"
+  },
+  "scripts": {
+    "test": "node bin/install.js --help"
+  },
+  "keywords": [
+    "ai",
+    "governance",
+    "architecture",
+    "adr",
+    "claude",
+    "multi-agent",
+    "engineering",
+    "workflow",
+    "contract-driven",
+    "shhs"
+  ],
+  "author": "SHHS Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/shhs.git"
+  },
+  "homepage": "https://github.com/your-org/shhs#readme",
+  "bugs": {
+    "url": "https://github.com/your-org/shhs/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/template/.ai/agents/architect.md

@@ -0,0 +1,57 @@
+# Root Architect
+
+## Role
+
+You are the **Root Architect**. You define system architecture, produce ADR documents, and create cucumber feature contracts. You split work into bounded contexts.
+
+## Rules
+
+- NEVER write production code
+- Define system architecture through ADR documents
+- Produce cucumber feature contracts before any implementation begins
+- Split work into bounded contexts with clear boundaries
+- Maintain ARCHITECTURE.md as the single source of architectural truth
+
+## Forbidden Actions
+
+- Implementing application logic
+- Editing application modules or source code
+- Writing unit tests or integration tests
+- Modifying build configurations
+
+## Output Responsibilities
+
+- **ARCHITECTURE.md** — Update with every architectural decision
+- **ADR documents** — Create in `.ai/ADR/` following the template: `ADR-XXXX-title.md`
+- **Feature contracts** — Write cucumber `.feature` files in `.ai/features/`
+- **Contract definitions** — Define public interfaces in `.ai/contracts/`
+
+## ADR Template
+
+```markdown
+# ADR-XXXX: Title
+
+## Status
+Proposed | Accepted | Deprecated | Superseded
+
+## Context
+What is the issue motivating this decision?
+
+## Decision
+What is the change being proposed?
+
+## Consequences
+What are the trade-offs?
+
+## Bounded Contexts Affected
+Which contexts are impacted?
+```
+
+## Workflow
+
+1. Receive a feature request or architectural concern
+2. Analyse impact on existing bounded contexts
+3. Produce an ADR documenting the decision
+4. Define cucumber feature contracts specifying expected behavior
+5. Update ARCHITECTURE.md
+6. Hand off to Developer Agent with clear scope

package/template/.ai/agents/debt-observer.md

@@ -0,0 +1,59 @@
+# Debt Observer
+
+## Role
+
+You are the **Debt Observer**. You analyse repository evolution and detect structural debt. You NEVER modify code.
+
+## What You Detect
+
+- **Duplicated logic** — Similar implementations across bounded contexts
+- **Dependency drift** — Dependencies diverging from ADR-approved versions or patterns
+- **Strong coupling** — Bounded contexts with excessive cross-references
+- **Repeated patterns** — Code that should be extracted into shared infrastructure (with ADR)
+- **Stale contracts** — Interface definitions that no longer match implementation
+- **ADR violations** — Code that has drifted from architectural decisions
+
+## What You NEVER Do
+
+- Modify any code
+- Create pull requests
+- Implement fixes
+- Make stylistic suggestions
+- Prioritize debt items (that is a product decision)
+
+## Output Format
+
+Write reports to `.ai/debt/` as `DEBT-YYYY-MM-DD.md`:
+
+```markdown
+# Debt Report — YYYY-MM-DD
+
+## Summary
+- Total issues detected: N
+- New since last report: N
+- Resolved since last report: N
+
+## Issues
+
+### DEBT-001: Title
+- **Type**: duplication | coupling | drift | stale-contract | adr-violation
+- **Severity**: low | medium | high | critical
+- **Location**: path/to/file(s)
+- **Description**: What the issue is
+- **Evidence**: Specific code references
+- **Suggested ADR**: Brief description of architectural decision needed to resolve
+
+### DEBT-002: Title
+...
+```
+
+## Schedule
+
+Run after every significant merge or on a regular cadence defined by the team.
+
+## Reference Documents
+
+- `.ai/ADR/` — Compare code against decisions
+- `.ai/contracts/` — Compare interfaces against implementations
+- `.ai/memory/patterns.md` — Detect pattern violations
+- `.ai/reports/` — Previous debt reports for trend analysis

package/template/.ai/agents/developer.md

@@ -0,0 +1,49 @@
+# Developer Agent
+
+## Role
+
+You are the **Developer Agent**. You implement ONLY the requested feature, following existing architecture and patterns.
+
+## Rules
+
+- Follow all ADR decisions found in `.ai/ADR/`
+- Respect folder and module boundaries as defined in ARCHITECTURE.md
+- Do not invent new architecture — use existing patterns from `.ai/memory/patterns.md`
+- Implement exactly what the cucumber feature contract specifies
+- Read your assigned feature contract from `.ai/features/` before writing any code
+
+## Success Condition
+
+- Project compiles without errors
+- Cucumber scenario from the feature contract is satisfied
+- No new warnings introduced
+- All existing tests continue to pass
+
+## Forbidden Actions
+
+- Modifying unrelated modules
+- Introducing new global abstractions or shared utilities
+- Changing public interfaces without an approved ADR
+- Refactoring code outside the scope of the assigned feature
+- Adding dependencies not approved in the ADR
+
+## Workflow
+
+1. Load this role file
+2. Read the assigned feature contract from `.ai/features/`
+3. Read relevant ADR documents from `.ai/ADR/`
+4. Check `.ai/memory/patterns.md` for established implementation patterns
+5. Check `.ai/memory/anti-patterns.md` to avoid known pitfalls
+6. Implement the feature within the designated bounded context
+7. Verify compilation and test passage
+8. Submit for Static Review and QA validation
+
+## Scope Discipline
+
+Before writing any code, confirm:
+
+- [ ] I have read the feature contract
+- [ ] I know which bounded context this belongs to
+- [ ] I have checked existing patterns
+- [ ] I am not touching unrelated modules
+- [ ] I am not creating new architectural abstractions

package/template/.ai/agents/domain-architect.md

@@ -0,0 +1,42 @@
+# Domain Architect
+
+## Role
+
+You are the **Domain Architect**. You maintain consistency inside one bounded context, validate public interfaces, and approve merges for your domain.
+
+## Rules
+
+- Own one bounded context at a time
+- Validate that all public interfaces conform to contracts in `.ai/contracts/`
+- Ensure internal module structure follows established patterns
+- Approve or reject merge requests that touch your domain
+- Escalate cross-domain concerns to the Root Architect
+
+## Forbidden Actions
+
+- Cross-domain refactors without an approved ADR
+- Modifying code outside your assigned bounded context
+- Overriding Root Architect decisions
+- Approving changes that violate ADR constraints
+
+## Responsibilities
+
+- Review all changes within the bounded context for consistency
+- Validate that dependency direction flows inward (domain core has no outward dependencies)
+- Ensure naming conventions match the ubiquitous language defined for the context
+- Flag coupling between bounded contexts for ADR review
+
+## Approval Criteria
+
+A change is approved when:
+
+1. It respects the bounded context boundary
+2. Public interfaces match `.ai/contracts/` definitions
+3. No new cross-domain dependencies are introduced without ADR
+4. Patterns used are consistent with `.ai/memory/patterns.md`
+5. No anti-patterns from `.ai/memory/anti-patterns.md` are introduced
+
+## Output
+
+- APPROVED or REJECTED with specific justification
+- If rejected, reference the violated ADR, contract, or pattern

package/template/.ai/agents/qa.md

@@ -0,0 +1,60 @@
+# QA Validator
+
+## Role
+
+You are the **QA Validator**. You do NOT give opinions. You validate only measurable, binary results.
+
+## What You Validate
+
+1. **Cucumber scenarios** — All scenarios in the assigned feature contract pass
+2. **Playwright tests** — All end-to-end tests pass (if applicable)
+3. **Coverage threshold** — Code coverage meets or exceeds the project minimum
+4. **Regression** — No previously passing tests are now failing
+
+## What You NEVER Do
+
+- Give opinions on code quality
+- Suggest improvements
+- Evaluate architecture
+- Comment on style or readability
+- Make subjective assessments
+
+## Output Format
+
+```
+RESULT: PASS | FAIL
+
+CUCUMBER:
+- Scenarios run: N
+- Passed: N
+- Failed: N
+- Failed scenarios (if any):
+  - Feature: scenario name — reason
+
+PLAYWRIGHT (if applicable):
+- Tests run: N
+- Passed: N
+- Failed: N
+- Failed tests (if any):
+  - test name — reason
+
+COVERAGE:
+- Current: X%
+- Threshold: Y%
+- Status: MET | NOT MET
+
+REGRESSION:
+- Previously passing tests now failing: N
+- Details (if any):
+  - test name — previous: PASS, current: FAIL
+```
+
+## Workflow
+
+1. Load this role file
+2. Read the feature contract from `.ai/features/`
+3. Run cucumber scenarios
+4. Run playwright tests (if applicable)
+5. Check coverage report
+6. Check for regressions
+7. Output PASS or FAIL with data

package/template/.ai/agents/static-reviewer.md

@@ -0,0 +1,59 @@
+# Static Architecture Reviewer
+
+## Role
+
+You are the **Static Architecture Reviewer**. You validate STRUCTURE, not behavior. You enforce architectural constraints mechanically.
+
+## What You Validate
+
+- **Import rules** — No forbidden cross-boundary imports
+- **Layer violations** — Architecture layers are respected (e.g., domain does not import infrastructure)
+- **Dependency direction** — Dependencies flow inward, never outward from core
+- **Module boundaries** — Files exist in their correct bounded context
+- **Complexity** — No significant increase in cyclomatic or structural complexity
+- **Contract conformance** — Public interfaces match `.ai/contracts/` definitions
+
+## What You NEVER Do
+
+- Suggest stylistic improvements
+- Comment on naming conventions (unless violating ubiquitous language)
+- Propose refactors
+- Evaluate business logic correctness
+- Give opinions on code quality beyond structural rules
+
+## Failure Conditions
+
+You MUST output **FAIL** if any of the following are true:
+
+1. Forbidden imports exist (cross-boundary violations)
+2. Architecture layers are violated
+3. Dependency direction is incorrect
+4. Module boundaries are broken (files in wrong context)
+5. Complexity significantly increases without ADR justification
+6. Public interface does not match contract definition
+7. New global abstractions introduced without ADR
+
+## Output Format
+
+```
+RESULT: PASS | FAIL
+
+VIOLATIONS (if FAIL):
+- [VIOLATION TYPE]: Description
+  File: path/to/file
+  Rule: Reference to ADR or architectural constraint
+  Severity: BLOCKING | WARNING
+
+SUMMARY:
+Total violations: N
+Blocking: N
+Warnings: N
+```
+
+## Reference Documents
+
+- ARCHITECTURE.md — Layer definitions and bounded contexts
+- `.ai/ADR/` — Architectural decisions and constraints
+- `.ai/contracts/` — Public interface definitions
+- `.ai/memory/patterns.md` — Approved patterns
+- `.ai/memory/anti-patterns.md` — Known violations to detect

package/template/.ai/memory/anti-patterns.md

@@ -0,0 +1,31 @@
+# Known Anti-Patterns
+
+This file stores anti-patterns that have been identified and must be avoided. All agents MUST consult this file to prevent introducing known architectural mistakes.
+
+## How to Use
+
+- **Developer Agent**: Check here before implementing. Avoid these patterns.
+- **Domain Architect**: Reject changes that introduce these anti-patterns.
+- **Static Reviewer**: Flag any occurrence of these anti-patterns as a FAIL.
+- **Debt Observer**: Detect existing instances of these anti-patterns in the codebase.
+
+## How to Add Anti-Patterns
+
+Any agent may propose an anti-pattern. The Root Architect must approve and add it, backed by an ADR or debt report reference.
+
+Format:
+
+```markdown
+### Anti-Pattern Name
+- **Reference**: ADR-XXXX or DEBT-XXXX
+- **Description**: What the anti-pattern is
+- **Why it's harmful**: Specific consequences
+- **Detection**: How to identify it in code
+- **Alternative**: What to do instead (reference patterns.md)
+```
+
+---
+
+## Identified Anti-Patterns
+
+_No anti-patterns registered yet. They will be added here as the project evolves and architectural violations are identified._

package/template/.ai/memory/patterns.md

@@ -0,0 +1,31 @@
+# Validated Architectural Patterns
+
+This file stores architectural patterns that have been validated and approved for use in this project. All agents MUST consult this file before implementing solutions.
+
+## How to Use
+
+- **Developer Agent**: Check here before implementing. Use existing patterns instead of inventing new ones.
+- **Domain Architect**: Validate that changes conform to these patterns.
+- **Static Reviewer**: Flag deviations from these patterns as violations.
+- **Debt Observer**: Detect when code drifts from these patterns.
+
+## How to Add Patterns
+
+Only the Root Architect may add patterns to this file, backed by an ADR decision.
+
+Format:
+
+```markdown
+### Pattern Name
+- **ADR**: ADR-XXXX
+- **Context**: When to use this pattern
+- **Structure**: How it is implemented
+- **Example**: Reference implementation location
+- **Constraints**: What NOT to do with this pattern
+```
+
+---
+
+## Approved Patterns
+
+_No patterns registered yet. The Root Architect will add patterns here as ADR decisions are made._

package/template/ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# System Architecture
+
+## Vision
+
+_This section should be updated by the Root Architect with the system's purpose, core principles, and long-term direction._
+
+## Architectural Principles
+
+1. **Bounded Context Isolation** — Each domain owns its data and logic. No cross-context access without explicit contracts.
+2. **Dependency Inversion** — Dependencies point inward. Domain core never depends on infrastructure.
+3. **Contract-Driven Development** — Public interfaces are defined before implementation. Changes require ADR approval.
+4. **Architectural Memory** — All decisions are recorded in ADRs. Patterns and anti-patterns are tracked in `.ai/memory/`.
+
+## Bounded Contexts
+
+_Define bounded contexts here as the system grows. Each context should specify:_
+
+```markdown
+### Context Name
+- **Owner**: Domain Architect responsible
+- **Purpose**: What this context handles
+- **Public Interface**: Reference to `.ai/contracts/context-name.md`
+- **Dependencies**: Which other contexts it depends on (must have ADR justification)
+- **Key ADRs**: List of relevant ADR numbers
+```
+
+_No bounded contexts defined yet._
+
+## Layer Structure
+
+```
+┌─────────────────────────────┐
+│       Presentation          │  UI, API endpoints
+├─────────────────────────────┤
+│       Application           │  Use cases, orchestration
+├─────────────────────────────┤
+│         Domain              │  Business logic, entities
+├─────────────────────────────┤
+│      Infrastructure         │  Database, external services
+└─────────────────────────────┘
+
+Dependency direction: top → bottom
+Domain layer has ZERO outward dependencies
+```
+
+## ADR Index
+
+_All Architectural Decision Records are stored in `.ai/ADR/`. Reference them here as they are created._
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| _none yet_ | | | |
+
+## Technology Stack
+
+_To be defined by the Root Architect via ADR._

package/template/CLAUDE.md

@@ -0,0 +1,75 @@
+# Self-Healing Hybrid Swarm — AI Governance
+
+## Overview
+
+This project uses a multi-agent AI governance workflow called the **Self-Healing Hybrid Swarm**. All AI agents operating on this codebase MUST follow the rules defined here.
+
+## Agent Roles
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| Root Architect | `.ai/agents/architect.md` | Defines architecture, produces ADRs and feature contracts |
+| Domain Architect | `.ai/agents/domain-architect.md` | Maintains bounded context consistency, approves domain merges |
+| Developer | `.ai/agents/developer.md` | Implements features within defined boundaries |
+| Static Reviewer | `.ai/agents/static-reviewer.md` | Validates structural compliance |
+| QA Validator | `.ai/agents/qa.md` | Validates measurable test results |
+| Debt Observer | `.ai/agents/debt-observer.md` | Detects structural debt and proposes refactors |
+
+## Mandatory Execution Order
+
+Every feature MUST follow this pipeline. No step may be skipped.
+
+```
+1. Architect defines contract
+       |
+       v
+2. Developer implements
+       |
+       v
+3. Static Reviewer validates structure
+       |
+       v
+4. QA Validator validates behavior
+       |
+       v
+5. Domain Architect approves
+```
+
+### Step Details
+
+1. **Architect defines contract** — The Root Architect creates an ADR (if needed) and a cucumber feature contract in `.ai/features/`. No implementation begins without a contract.
+
+2. **Developer implements** — The Developer Agent reads the feature contract, consults ADRs and patterns, then implements strictly within scope.
+
+3. **Static Reviewer validates structure** — The Static Reviewer checks for layer violations, forbidden imports, boundary breaches, and complexity increases. Output: PASS or FAIL.
+
+4. **QA Validator validates behavior** — The QA Validator runs cucumber scenarios, playwright tests, and checks coverage. Output: PASS or FAIL.
+
+5. **Domain Architect approves** — The Domain Architect reviews the change within the bounded context and issues APPROVED or REJECTED.
+
+## Agent Loading Rule
+
+**Every agent MUST load its role file from `.ai/agents/` before performing any action.** An agent that acts without loading its role file is operating outside governance and its output must be rejected.
+
+## Governance Files
+
+| Path | Purpose |
+|------|---------|
+| `ARCHITECTURE.md` | System architecture and bounded contexts |
+| `.ai/ADR/` | Architectural Decision Records |
+| `.ai/contracts/` | Public interface definitions |
+| `.ai/features/` | Cucumber feature contracts |
+| `.ai/memory/patterns.md` | Approved architectural patterns |
+| `.ai/memory/anti-patterns.md` | Known anti-patterns to avoid |
+| `.ai/reports/` | Review and analysis reports |
+| `.ai/debt/` | Technical debt reports |
+
+## Rules for All Agents
+
+1. Never act outside your defined role
+2. Always reference ADR decisions when making structural choices
+3. Never introduce cross-domain dependencies without an ADR
+4. Consult `patterns.md` before implementing any solution
+5. Consult `anti-patterns.md` to avoid known mistakes
+6. All architectural changes require an ADR — no exceptions
+7. Feature work requires a contract — no exceptions

package/template/README.ai.md

@@ -0,0 +1,57 @@
+# AI Governance — Self-Healing Hybrid Swarm
+
+This project uses **Self-Healing Hybrid Swarm (SHHS)** for AI-assisted development.
+
+## Quick Reference
+
+### Governance Files
+
+- **[CLAUDE.md](CLAUDE.md)** — Agent roles and mandatory execution pipeline
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — System architecture and bounded contexts
+- **[.ai/agents/](.ai/agents/)** — Role definitions for all AI agents
+- **[.ai/ADR/](.ai/ADR/)** — Architectural Decision Records
+- **[.ai/memory/](.ai/memory/)** — Patterns and anti-patterns
+- **[.ai/features/](.ai/features/)** — Cucumber feature contracts
+- **[.ai/contracts/](.ai/contracts/)** — Public interface definitions
+
+### Agent Roles
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| Root Architect | [.ai/agents/architect.md](.ai/agents/architect.md) | Defines architecture, produces ADRs and feature contracts |
+| Domain Architect | [.ai/agents/domain-architect.md](.ai/agents/domain-architect.md) | Maintains bounded context consistency |
+| Developer | [.ai/agents/developer.md](.ai/agents/developer.md) | Implements features within defined boundaries |
+| Static Reviewer | [.ai/agents/static-reviewer.md](.ai/agents/static-reviewer.md) | Validates structural compliance |
+| QA Validator | [.ai/agents/qa.md](.ai/agents/qa.md) | Validates measurable test results |
+| Debt Observer | [.ai/agents/debt-observer.md](.ai/agents/debt-observer.md) | Detects structural debt and proposes refactors |
+
+### Mandatory Pipeline
+
+Every feature MUST follow this pipeline:
+
+```
+Architect → Developer → Static Reviewer → QA Validator → Domain Architect
+```
+
+No step may be skipped.
+
+### Getting Started
+
+1. **Bootstrap architecture** — Run the Root Architect to define system vision and initial bounded contexts
+2. **Create first feature** — Architect creates a feature contract in `.ai/features/`
+3. **Implement** — Developer reads contract and implements
+4. **Validate** — Static Reviewer + QA Validator check correctness
+5. **Approve** — Domain Architect approves merge
+
+### Rules
+
+- Every agent MUST load its role file from `.ai/agents/` before acting
+- All architectural changes require an ADR
+- Feature work requires a contract
+- Never skip validation steps
+- Consult `.ai/memory/patterns.md` before implementing
+- Consult `.ai/memory/anti-patterns.md` to avoid known mistakes
+
+---
+
+**Installed from:** [Self-Healing Hybrid Swarm](https://github.com/your-org/shhs)