# DevOS v1 ZCODE Development Specification

## 1. Purpose
This document converts the architecture into executable work units for an AI coding agent such as ZCODE, Codex, Cursor or Claude Code.

The agent must work from specifications instead of inventing architecture during implementation.

## 2. Repository Target

```text
devos/
├── apps/
│   ├── web/
│   └── api/
├── packages/
│   ├── ui/
│   ├── api-client/
│   ├── types/
│   └── auth/
├── packages/integrations/
├── prisma/
├── docs/
├── specs/
└── AGENTS.md
```

## 3. Initial Task Queue

### Task 001 — Monorepo
Create the workspace structure for web, API and shared packages.

Acceptance:
- package manager/workspaces configured
- TypeScript shared configuration
- lint/format/test commands
- build pipeline

### Task 002 — Backend Bootstrap
Create NestJS API with versioned `/api/v1` routing.

Acceptance:
- health endpoint
- configuration management
- structured logging
- error handling
- request ID

### Task 003 — Frontend Bootstrap
Create React + Ant Design application.

Acceptance:
- ProLayout
- routing
- authentication shell
- dashboard shell
- API client
- loading/error/empty states

### Task 004 — Database
Create PostgreSQL + Prisma setup.

Acceptance:
- migrations
- core identity/workspace/resource schema
- seed strategy
- database documentation

### Task 005 — Authentication
Implement authentication and current-user endpoint.

Acceptance:
- login/logout
- session/token strategy
- password/credential handling appropriate to chosen auth design
- authorization guards

### Task 006 — Workspace
Implement workspace and membership.

Acceptance:
- create/list/read workspace
- membership
- workspace isolation in service and query layers

### Task 007 — Resource System
Implement unified Resource abstraction.

Acceptance:
- CRUD
- typed resource type
- status
- metadata
- relation graph
- workspace scope

### Task 008 — Audit
Implement audit service and mutation hooks.

Acceptance:
- audit record for every mutation
- actor/workspace/resource/action
- request/correlation ID
- sensitive data masking

### Task 009 — Server Module
Implement Server resource and provider adapter.

Acceptance:
- create server
- credential reference
- connectivity check
- status
- SSH execution
- audit
- timeout/error handling

### Task 010 — Docker
Implement Docker discovery through Server integration.

Acceptance:
- list containers
- inspect container
- restart container
- resource relation
- audit

### Task 011 — Website
Implement Website domain model and UI.

Acceptance:
- website CRUD
- repository/server/domain relations
- status
- detail page

### Task 012 — Deployment
Implement deployment job model and asynchronous execution.

Acceptance:
- create deployment
- run deployment
- progress
- logs
- cancellation where safe
- verification
- success/failure events

### Task 013 — Domain
Implement domain and DNS provider adapter.

Acceptance:
- domain CRUD
- record read/update
- authorization
- audit

### Task 014 — Monitoring
Implement initial health checks.

Acceptance:
- website health
- server status
- monitor result history
- down/recovered events

### Task 015 — Event Bus
Implement internal domain events and persistence/dispatch model.

Acceptance:
- canonical event names
- correlation IDs
- durable execution for required events

### Task 016 — Automation
Implement Trigger → Condition → Action workflow model.

Acceptance:
- manual trigger
- event trigger
- cron design
- execution history
- retries/timeouts

### Task 017 — AI Gateway
Implement an AI run abstraction without allowing unrestricted execution.

Acceptance:
- create AI run
- plan
- tool registry
- risk evaluation
- approval state
- execution history
- verification result

### Task 018 — MCP
Expose selected DevOS capabilities through MCP.

Acceptance:
- server list/status
- website list/deploy
- deployment get
- domain list/records
- task/note tools when corresponding modules exist
- all requests pass normal authorization/audit/risk controls

## 4. Agent Execution Protocol

For each task:
1. Read relevant docs.
2. Inspect existing code.
3. State implementation plan internally.
4. Implement the smallest coherent change.
5. Add/update tests.
6. Run typecheck/lint/tests.
7. Verify API and UI contracts.
8. Update documentation.
9. Do not refactor unrelated code.

## 5. Stop Conditions
The coding agent must stop and ask for a human decision when:
- architecture requires a new major dependency
- a security boundary must change
- destructive production behavior is requested
- domain terminology conflicts with existing specifications
- an API breaking change is unavoidable
- two specification documents materially conflict

## 6. Priority
When requirements conflict, use this order:
1. Security
2. Explicit user requirement
3. Domain model
4. API contract
5. Architecture
6. UI convenience
7. Implementation preference

## 7. Important Constraint
Do not convert DevOS into microservices during V1 unless a concrete operational requirement proves modular monolith insufficient.