muse-agents

# muse-agents - Full Canonical Knowledge Base

Generated on: 2026-09-01T14:26:26.388Z


=======================================================
FILE: docs/01_OVERVIEW.md
=======================================================

# Project Overview: muse-agents

## 1. Executive Summary
- **Project Name**: muse-agents
- **Archetype**: GENERIC (Latest)
- **Objective**: Muse Agents - harness-independent AI agent framework for agency operations. Thin agent personas + optional service packs + adapters for any AI harness.
- **Target Audience / Stakeholders**: Agency clients, end-users, and internal operators.

## 2. Core Value Proposition
- High-velocity, beautifully crafted, and rigorously tested application.
- Governed by the LifeOS Agency Council (Muse, Sol, Jasper, Crew, Nexus).

## 3. Success Metrics & KPIs
- Sub-second page load times (Core Web Vitals 95+).
- Zero TypeScript & lint errors on main branch.
- Full automated test and visual probe verification.


=======================================================
FILE: docs/02_ARCHITECTURE.md
=======================================================

# Architecture & Runtime Topology

## 1. Stack Specifications
- **Format**: Harness-neutral YAML frontmatter Markdown definitions (`spec/agent-format.md`)
- **Language**: TypeScript / Bun / Node.js / Python3
- **Adapters**: OpenCode subagents, Codex TOML, Claude Code
- **Validation**: Python/Bun specification validator and automated test suite

## 2. Multi-Agent Topology & Gauntlet Loop
- **Gauntlet Loop**: Bounded iterative refinement pack (`packs/gauntlet/`)
  - `[User/Prompt] -> [Judge: Freeze Contract] -> [Builder: Write Diff] -> [Critic: Fresh Review with review.json] -> [Judge: Pass or Fix] -> (Fix -> [Integrator: Apply 1 Largest Fix] -> Critic | Pass -> [Complete])`
- **Governed Secretary**: Evidence-grounded staff-work synthesizer (`agents/ops/secretary.md` & `packs/secretary/`) with SHA-256 approval tokens and dissent mandates.
- **Quality Gate**: Adversarial quality verification via `nexus-reviewer`.

## 3. Directory Layout
```
muse-agents/
├── adapters/         # Target harness renderers (opencode, codex, claude-code)
├── agents/           # 21 core agent personas across 8 divisions
├── packs/            # 13 opt-in specialized packs (gauntlet, secretary, etc.)
├── scripts/          # build, install, llms generator, nexus verify
├── spec/             # Canonical agent and pack specifications
├── tests/            # Unit and probe test suites
├── AGENTS.md         # Framework contract and dispatch rules
├── README.md         # Documentation and quick start
├── STATE.md          # Reality state
├── SUMMARY.md        # Change ledger
├── llms.txt          # LLM discovery index
└── llms-full.txt     # Complete bundled documentation
```


=======================================================
FILE: docs/03_ESCALATION_RULES.md
=======================================================

# Escalation Hierarchy & Anti-Overengineering (Ponytail Doctrine)

## The 4-Tier Escalation Order
Before writing custom code or generating heavy automation, evaluate solutions in this strict sequence:

1. **Tier 1 (Simplest / Preferred)**: Native Platform Config, Dashboard setting, or Environment variable.
2. **Tier 2 (Minimal)**: Simple CSS utility, standard framework hook, or existing helper (<15 lines).
3. **Tier 3 (Controlled)**: Dedicated UI component or standard API route handler.
4. **Tier 4 (Last Resort)**: Complex state machine, custom microservice, or 400-line automation harness.

> *"Sometimes clicking a checkbox in an admin panel or using a single CSS class is infinitely better than generating 400 lines of glue code."*


=======================================================
FILE: docs/04_DESIGN_SYSTEM.md
=======================================================

# Design System & Style Architecture

## 1. Visual Philosophy (Jasper)
- Clean visual hierarchy, curated color ramps (OKLCH / HSL tailored tokens), balanced whitespace.
- Micro-interactions with purposeful motion (smooth, snappy, non-distracting).
- Responsive by default: Mobile-first fluid adaptation.

## 2. Token Standards
- **Typography**: Tailored modern font scales with precise letter-spacing and line-height.
- **Colors**: Strict background, foreground, primary, muted, border, and accent tokens.
- **Motion**: Standard cubic-bezier curves for transitions; respect `prefers-reduced-motion`.


=======================================================
FILE: docs/05_DECISION_LOG.md
=======================================================

# Architectural Decision Records (ADR)

## Format
Every major architectural decision is recorded using this schema:

### [ADR-001] Project OS Initialization
- **Date**: 2026-08-24
- **Status**: APPROVED
- **Context**: Initialized the project with the LifeOS Agency Council operating system.
- **Decision**: Adopted the 10 Canonical Docs, 8-Stage Reality Machine, Meaningful Git Commit Protocol, and Nexus verification harness.
- **Consequences**: Deterministic state tracking, anti-hallucination guardrails, and zero secret leakage.


=======================================================
FILE: docs/06_ENVIRONMENTS.md
=======================================================

# Environments & Deployment Topology

## 1. Environment Stages
1. **LOCAL**: Development workspace (`http://localhost:3000` or `http://localhost:4321`).
2. **STAGING / PREVIEW**: Ephemeral or dedicated staging for review and Playwright testing.
3. **PRODUCTION**: Live customer-facing environment.

## 2. Secrets Policy
- Secrets are NEVER stored in git or shared project docs.
- Use `.env.example` to document expected variable keys without values.


=======================================================
FILE: docs/07_RUNTIME_STATE.md
=======================================================

# Verified Runtime State

## 1. Current Environment Snapshot
- **Last Verified Date**: 2026-08-24
- **Node / Bun Version**: Bun 1.4.0
- **Active Dependencies**: Initialized with latest framework packages

## 2. Infrastructure Health
- Dev server: Configured
- Typecheck: Ready
- Build pipeline: Ready


=======================================================
FILE: docs/08_WORKSTREAMS.md
=======================================================

# Active Workstreams & Division Ownership

| Workstream ID | Area | Lead | Status | Active Focus |
|---|---|---|---|---|
| **WS-01** | Product & Development | Sol | SHIPPED | Frontend, backend, CMS, code reviewer, Gauntlet builder & integrator |
| **WS-02** | Growth & Verification | Jasper | SHIPPED | UI/UX, brand, copy, SEO, and source Fact-Checker |
| **WS-03** | Delivery & Governance | Crew | SHIPPED | Client delivery, hosting, Governed Secretary & Chief of Staff |
| **WS-04** | Quality Gate & Gauntlet | Nexus | SHIPPED | Adversarial verification, Gauntlet critic & judge, SecretScan |



=======================================================
FILE: docs/09_HARNESS_PROBES.md
=======================================================

# Nexus Contract Probes & Test Criteria

## 1. Deterministic Probes
- **Build Probe**: `npm run build` must exit with code 0.
- **Typecheck Probe**: `npm run typecheck` must return 0 errors.
- **Vibeguard Probe**: `bun ~/.config/LIFEOS/runtime/TOOLS/SecretScan.ts .` must return 0 leaks.

## 2. Runtime & Browser Probes (Playwright)
- **Route Probe**: `GET /` returns HTTP 200.
- **DOM Probe**: Key layout container renders without crash.
- **Console Probe**: Zero uncaught runtime errors in browser console.


=======================================================
FILE: docs/10_UNRESOLVED.md
=======================================================

# Unresolved Questions & Parking Lot

## 1. Open Architectural Questions
- [ ] Finalize production deployment target (Vercel, Cloudflare, VPS, Docker).
- [ ] Define third-party API integrations and webhooks.

## 2. Parking Lot
- Ideas discussed but not yet approved for the active roadmap.


=======================================================
FILE: STATE.md
=======================================================

# Reality State Machine

> **Rule**: An item only moves from PROPOSED to PROD_VERIFIED when verified with deterministic evidence.

```
[PROPOSED] → [APPROVED] → [LOCAL_DEV] → [LOCAL_VERIFIED] → [STAGING_DEPLOYED] → [STAGING_VERIFIED] → [PROD_DEPLOYED] → [PROD_VERIFIED]
```

## Current Workstream States

| Item / Feature | State | Owner | Verification Evidence |
|---|---|---|---|
| **Project Framework & Spec** | `PROD_VERIFIED` | Muse | `spec/agent-format.md`, `build.sh --check` pass |
| **21 Core Agent Personas** | `PROD_VERIFIED` | Sol/Jasper/Crew/Nexus | 21 core agents across 8 divisions verified |
| **Gauntlet Multi-Agent Loop** | `PROD_VERIFIED` | Nexus/Sol | `packs/gauntlet/` manifest + 4 agents pass |
| **Governed Secretary Pack** | `PROD_VERIFIED` | Crew | `packs/secretary/` manifest + 4 agents pass |
| **Multi-Harness Adapters** | `PROD_VERIFIED` | Sol | OpenCode, Codex, Claude Code renderers pass |
| **Automated Test Suite** | `PROD_VERIFIED` | Nexus | 24 bun tests passing across unit test suites |