# CONTEXT.md

## Software Development Team

**Status:** Active - Team creation in progress  
**Last Updated:** 2026-07-03

### Purpose
A dedicated multi-agent software development team for Beawit's internal applications and automation tooling.

### Team Structure

| Agent ID | Role | Responsibilities | Model |
|----------|------|------------------|-------|
| **dev-product** | Product Manager | Requirements, user stories, feature prioritization, acceptance criteria | kimi-k2.5:cloud |
| **dev-architect** | Architect | System design, API design, data models, tech decisions | kimi-k2.5:cloud (reasoning) |
| **dev-backend** | Backend Developer | APIs, databases, integrations, business logic | qwen3-coder:480b-cloud |
| **dev-frontend** | Frontend Developer | UI/UX, components, client state, styling | qwen3-coder:480b-cloud |
| **dev-qa** | QA Engineer | Test plans, automated tests, bug reproduction | glm-4.7:cloud |
| **dev-devops** | DevOps Engineer | Deployments, CI/CD, monitoring, infrastructure | kimi-k2.5:cloud |
| **dev-lead** (me) | Tech Lead | Coordination, code review, integration, delegation | kimi-k2.5:cloud |

### Workspace Organization

### Directory Structure
```
workspace/
├── Core Config (keep in root)
│   ├── IDENTITY.md, SOUL.md, AGENTS.md
│   ├── MEMORY.md, CONTEXT.md, PROJECTS.md
│   ├── USER.md, TOOLS.md, HEARTBEAT.md
│   └── ARCHITECTURE.md
│
├── docs/           # Documentation files
│   ├── summaries/  # *SUMMARY.md files
│   ├── plans/      # *PLAN.md files
│   ├── inventories/ # *INVENTORY.md files
│   └── *.md        # Other documentation
│
├── scripts/        # Executable scripts
│   ├── checks/     # check-*.sh scripts
│   ├── fixes/      # fix-*.sh, fix-*.js
│   └── utils/      # get-*, update-*, debug-*
│
├── tests/          # Test and debug files
├── runtime/        # Package and state files
├── architecture/   # Architecture components
├── memory/         # Memory system files
└── Projects/       # Project directories
```

### Organization Rules
1. **Core config stays in root** - Never move IDENTITY.md, SOUL.md, etc.
2. **New documentation goes to docs/** - Sort by type (summaries, plans, inventories)
3. **New scripts go to scripts/** - Categorize by purpose (checks, fixes, utils)
4. **Test files go to tests/** - Any test-* or debug-* files
5. **Runtime files go to runtime/** - package.json, state files, binaries
6. **Run organizer monthly** - `bash ~/.openclaw/skills/workspace-organizer/scripts/organize-workspace.sh --dry-run`

### Maintenance
- Use `WORKSPACE_ORGANIZATION_LOG.md` to track changes
- Run dry-run before executing organization
- Archive old fix scripts after 30 days
- Clean temp files weekly

---

## Technology Stack
- **Backend:** Python (FastAPI) — chosen for type hints, async support, and your existing Python codebase
- **Frontend:** HTMX + Jinja2 templates — lightweight, server-rendered, minimal JavaScript complexity
- **Database:** PostgreSQL for production, SQLite for local dev
- **Infrastructure:** Docker containers, VPS deployment via SSH
- **Version Control:** Git with feature branch workflow

### Workflow

1. **Intent Classification** → Orchestrator classifies request using workflow-router
2. **Context Building** → Preprocessing pipeline loads rules, preferences, memory
3. **Feature Request** → dev-product creates user stories + acceptance criteria
4. **Design** → dev-architect designs system changes, API contracts
5. **Implementation** → dev-backend + dev-frontend work in parallel
6. **Review** → dev-lead reviews code, requests changes if needed
7. **Validation** → Automated checks via validation layer + format locker
8. **Testing** → dev-qa validates against acceptance criteria
9. **Deploy** → dev-devops deploys to staging, then production
10. **Verify** → dev-lead confirms deployment success

## Architecture Components

| Component | File | Purpose |
|-----------|------|---------|
| Orchestrator | `architecture/orchestrator.js` | Main integration point |
| Pipeline | `architecture/pipeline.js` | Context preprocessing |
| Workflow Router | `architecture/workflow-router.js` | Intent classification |
| Validator | `architecture/validator.js` | Response quality checks |
| Format Locker | `architecture/format-locker.js` | Output template enforcement |

### Usage Examples

```bash
# Classify intent
node architecture/workflow-router.js "deploy the app to production"

# Validate a response
node architecture/validator.js deploy /tmp/response.md

# Enforce format
node architecture/format-locker.js coding /tmp/response.md

# Full pipeline
node architecture/orchestrator.js "your request here" --verbose
```

### Current Tasks
- [x] Define team agent structure
- [x] Create agent instruction files
- [x] Establish workflow protocols
- [x] Test first delegation cycle
- [x] Enhance site survey application with dashboard
- [x] Implement memory system for context persistence
- [x] Deploy super-enhanced memory system with JavaScript engine
- [x] Implement workflow router with intent classification
- [x] Deploy validation layer with safety checks
- [x] Deploy format locker with auto-fix
- [x] Integrate all components via orchestrator

### Decisions Log
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-07-03 | Create dedicated dev team | Need scalable capacity for multiple internal app projects |
| 2026-07-03 | Python/FastAPI + HTMX stack | Matches existing skills, FastAPI's type safety, HTMX keeps frontend simple |