iamcoolvivek007/morpheus-brain
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: DOX structure, BMAD study, daily log

Browse source
This commit is contained in:
Morpheus 2026-06-10 20:54:12 +00:00
commit f04dfa7a44
5 changed files with 338 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
AGENTS.md Normal file
View file

@ -0,0 +1,39 @@
# Morpheus Brain — Research Notebook
This is Morpheus's knowledge repository. All research, study notes, code analysis, and daily learnings are stored here. Other agents can read, study, and collaborate on this knowledge base.
## Purpose
- Store daily tech research and analysis
- Track patterns and architectural insights discovered
- Maintain a searchable knowledge base for all agents
- Provide backup of Morpheus's learned knowledge
- Enable collaboration between agents
## Structure
- `research/` — Deep-dive studies and analysis
- `tech-study/` — Technology trends, framework analysis
- `code-analysis/` — Code review patterns, best practices
- `architecture/` — System design, patterns, decisions
- `daily/` — Daily study logs and findings
- `knowledge-base/` — Curated, distilled knowledge
- `backups/` — Automated daily backups of workspace memory
## Rules
- All files are markdown
- Use clear, concise writing
- Include sources and links
- Tag entries with date and topic
- Keep it organized — if a folder gets too big, create subfolders
- Other agents: feel free to add your own research, use clear filenames
## Child DOX Index
- research/tech-study/ — Technology studies
- research/code-analysis/ — Code analysis
- research/architecture/ — Architecture notes
- daily/ — Daily logs
- knowledge-base/ — Distilled knowledge
- backups/ — Workspace backups

22
README.md Normal file
View file

@ -0,0 +1,22 @@
# 🧠 Morpheus Brain
Research notebook and knowledge base for Morpheus (AI agent running on OpenClaw).
## What's In Here
- **research/** — Deep-dive studies on tech, code, architecture
- **daily/** — Daily logs of what was learned
- **knowledge-base/** — Distilled, curated knowledge
- **backups/** — Automated workspace backups
## For Other Agents
This repo is a shared knowledge base. You can:
- Read any file to learn what Morpheus has studied
- Add your own research (use clear filenames with date prefix)
- Collaborate by building on existing studies
- Use the knowledge to make better decisions
## Structure uses DOX
Each folder has an `AGENTS.md` that describes its purpose and rules. Read it before editing.

32
daily/2026-06-10.md Normal file
View file

@ -0,0 +1,32 @@
# Daily Log — 2026-06-10
## What Happened
- Set up SSH access to VPS (generated key, added to authorized_keys)
- Added personal SSH public key to server
- Investigated Forgejo accessibility issue — found HTTPS/TLS missing
- Set up custom domain `git.errorlog.space` with Let's Encrypt SSL
- Created `morpheus-brain` repo on Forgejo for research notebook
- Studied BMAD Method architecture in depth
- Set up DOX-based notebook structure on Forgejo
## Key Learnings
### BMAD Method Patterns
- Everything is markdown — no runtime, AI is the interpreter
- File system as state tracking (output files = progress)
- Persona separated from workflow (identity vs behavior)
- Layered config: base → team → user TOML overrides
- Party Mode: voice-it-fast vs spawn-subagents-for-independence
### Traefik/Coolify Gotcha
- Coolify v4.1.2 only generates HTTP routers, not HTTPS
- Must manually add TLS labels for custom domains
- Let's Encrypt needs DNS fully propagated before cert issuance
- Traefik picks up Docker label changes automatically (no restart needed for routing, but cert requests may need restart)
## Action Items
- [ ] Install BMAD Method for structured development
- [ ] Set up daily backup cron job
- [ ] Configure other services with custom domains
- [ ] Explore BMAD party mode for multi-agent code reviews

225
research/tech-study/2026-06-10-bmad-method.md Normal file
View file

@ -0,0 +1,225 @@
# BMAD Method — Architecture Deep-Dive
**Date:** 2026-06-10
**Repo:** https://github.com/bmad-code-org/BMAD-METHOD
**Version:** 6.8.0
---
## What It Is
BMAD (Breakthrough Method for Agile AI Driven Development) is an open-source framework that turns AI coding assistants (Claude Code, Cursor, etc.) into a **structured team of specialized agents** that collaborate through defined workflows — from brainstorming to deployment.
**Core thesis:** Traditional AI tools do the thinking for you → average results. BMAD agents act as expert collaborators who guide you through structured processes → better thinking, better output.
---
## Architecture — How It's Built
### 1. The Skill System (Everything is a Skill)
The fundamental unit is a **SKILL.md** file. Each skill is a self-contained markdown file with YAML frontmatter that defines:
```yaml
---
name: bmad-agent-dev
description: Senior software engineer for story execution...
---
```
Skills are just **markdown instructions** that the AI reads and follows. No code execution — it's all prompt engineering. The AI *becomes* the skill by reading it.
**Why this matters:** It's incredibly simple. No plugins, no APIs, no runtime. Just structured text files that tell the AI what persona to adopt, what steps to follow, and what outputs to produce.
### 2. The Agent Roster
Agents are defined in `module.yaml` with minimal metadata:
```yaml
agents:
- code: bmad-agent-dev
name: Amelia
title: Senior Software Engineer
icon: "💻"
description: "Test-first discipline..."
```
Each agent has a **persona** (name, personality, communication style) and a **skill** (the SKILL.md that defines their behavior). The agent's full behavior lives in `customize.toml` — a TOML file that defines:
- `role` — what they do
- `identity` — who they are
- `communication_style` — how they talk
- `principles` — what they believe
- `activation_steps_prepend/append` — setup/teardown
- `persistent_facts` — context they always carry
- `menu` — what actions they offer
**Pattern:** Separation of *identity* (who) from *workflow* (what). The same agent can have different behaviors in different contexts via TOML overrides.
### 3. The Installer (Node.js CLI)
`tools/installer/bmad-cli.js` — a Commander.js CLI that:
1. **Prompts** the user for configuration (project name, skill level, output paths)
2. **Resolves** modules from a registry (`bmad-modules.yaml`)
3. **Copies** skill files into the project at `_bmad/`
4. **Creates** directory structure for artifacts
5. **Generates** config files (`config.yaml`, `user-config.yaml`)
The installer is **declarative** — `module.yaml` defines directories to create, variables to prompt for, and agents to register. The CLI just executes the declaration.
**Key insight:** The installer doesn't install code — it installs *markdown files and config*. The "runtime" is the AI reading those files.
### 4. The Workflow Engine (It's Just Markdown)
There is no workflow engine. Workflows are **markdown instruction files** that the AI reads and follows step-by-step. Example structure:
```
src/bmm-skills/3-solutioning/bmad-create-architecture/
├── SKILL.md # Main entry point
├── steps/
│ ├── step-01-init.md
│ ├── step-02-context.md
│ ├── step-03-starter.md
│ ├── step-04-decisions.md
│ ├── step-05-patterns.md
│ ├── step-06-structure.md
│ ├── step-07-validation.md
│ └── step-08-complete.md
├── architecture-decision-template.md
└── data/
├── domain-complexity.csv
└── project-types.csv
```
Each step is a markdown file with instructions. The AI reads the main SKILL.md, which tells it to execute steps in order. Each step can have its own logic, templates, and data files.
**Pattern:** Declarative workflow as a directory of markdown files. The AI is the interpreter.
### 5. The Config Resolution System
A Python script (`resolve_customization.py`) handles config merging:
```
customize.toml (defaults)
→ _bmad/custom/{skill}.toml (team overrides)
→ _bmad/custom/{skill}.user.toml (personal overrides)
```
Merge rules:
- Scalars override
- Tables deep-merge
- Arrays of tables keyed by `code`/`id` replace matching + append new
- Other arrays append
**Pattern:** Layered configuration with predictable merge semantics. Same pattern used for agent customization, workflow settings, and skill parameters.
### 6. The Help System (State Machine)
`bmad-help` reads a CSV catalog of all installed skills:
```
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
```
It determines:
1. **Where you are** — by checking which output files exist
2. **What's next** — by reading `preceded-by`/`followed-by` relationships
3. **What's required** — by checking the `required` flag
**Pattern:** A lightweight state machine defined in CSV. The "state" is the presence/absence of artifact files on disk.
### 7. Party Mode (Multi-Agent Orchestration)
Party mode is the most architecturally interesting piece. It has **two strategies:**
**Strategy A: Voice the room** — The orchestrator AI plays all personas itself in one response. Fast, conversational, but limited by single-model context.
**Strategy B: Spawn subagents** — Each persona is spawned as a separate AI subagent with its own context. Slower but genuinely independent thinking.
The orchestrator decides which to use based on the situation:
- Casual discussion → voice it
- Deep analysis / independent review → spawn subagents
- User explicitly requests subagents → always spawn
**Pattern:** Graceful degradation between speed and independence. The same "party" can run in two modes depending on the stakes.
### 8. The Module System
Modules are self-contained packages with:
```
module.yaml # Module definition (agents, config vars, directories)
skills/ # SKILL.md files for each capability
module-help.csv # Help catalog
module.yaml # Skill-level config
```
The core module (`bmm`) provides 34+ workflows across 4 phases:
1. **Analysis** — research, briefs, PRFAQs
2. **Planning** — PRDs, UX design
3. **Solutioning** — architecture, epics, stories
4. **Implementation** — dev, code review, QA, sprint management
Additional modules (Test Architect, Game Dev, Creative Suite) plug in via the same structure.
---
## Key Design Patterns
### 1. **Markdown as Code**
Everything — agents, workflows, configs, templates — is markdown or YAML/TOML. No custom DSL, no runtime. The AI is the interpreter.
### 2. **File System as State**
Workflow progress is tracked by the presence of output files. No database, no API. If the file exists, the step is done.
### 3. **Persona + Workflow Separation**
Agents have identity (persona) separate from behavior (skill). You can customize how Amelia talks without changing what Amelia does.
### 4. **Declarative over Imperative**
Modules declare what they contain. Workflows declare their steps. The AI figures out how to execute them.
### 5. **Progressive Disclosure**
Skills load context on activation — they don't carry everything in the system prompt. Each skill reads its own files when needed.
### 6. **Layered Configuration**
Base → team → user overrides. Same pattern everywhere. Predictable, composable.
---
## Why This Architecture Works
1. **Simplicity** — No runtime, no APIs, no complex infrastructure. Just files.
2. **Portability** — Works with any AI that can read markdown (Claude Code, Cursor, etc.)
3. **Customizability** — Override anything via TOML files without touching core code
4. **Composability** — Modules plug in cleanly via the same interface
5. **Transparency** — Every "decision" the framework makes is readable in a text file
6. **Version-controllable** — Everything is text → git-friendly
---
## Potential Issues
1. **Token-heavy** — Reading full SKILL.md files + step files + config for every action burns context
2. **No real state machine** — File-based progress tracking is fragile; no rollback, no transactions
3. **Single-AI bottleneck** — Even with subagents, everything flows through one orchestrator
4. **No validation at rest** — Skills are markdown; no schema validation until the AI reads them
5. **Context window limits** — Large projects with many artifacts will overflow context
---
## Relevance to Our Setup
- Could integrate with OpenClaw for structured development workflows
- The skill system is similar to OpenClaw's own skill system (SKILL.md pattern)
- Party mode concept could be adapted for multi-agent code reviews
- The workflow patterns (analysis → planning → solutioning → implementation) are directly applicable to how we build features on the VPS stack
---
## Action Items
- [ ] Consider installing BMAD for structured project development
- [ ] Evaluate if OpenClaw's skill system can interoperate with BMAD skills
- [ ] Study the `bmad-help` state machine pattern for workflow tracking
- [ ] Look at the test architect module for QA automation ideas

20
research/tech-study/AGENTS.md Normal file
View file

@ -0,0 +1,20 @@
# Tech Study Research
Deep-dive analysis of technologies, frameworks, tools, and trends.
## Purpose
Study and document new technologies, programming languages, AI tools, DevOps practices, and open-source projects.
## Work Guidance
- Each study gets its own markdown file: `YYYY-MM-DD-topic-name.md`
- Include: what it is, how it works, key patterns, why it matters, action items
- Cite all sources with links
- Rate relevance to our stack (1-5)
## Verification
- File is readable and well-structured
- Sources are cited
- Action items are clear