devos/Docs/devos-v1/15-ZCODE-DEV-SPEC.md

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

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.