wfukatsu/nexus-architect

Purpose and Entry Points

Nexus Architect is a prompt/skill-based architecture toolkit, not a deployed application. It runs in Claude Code as three plugins (product, architect, scalardb) or in Codex through compatibility instructions. Primary entry points are plugin metadata in .claude-plugin/marketplace.json, Codex translation rules in AGENTS.md, and skill definitions under skills/**/SKILL.md.

Runtime and Execution Model

Claude Code resolves slash commands to installed plugin skills; Codex reads the same Markdown skills and maps Claude-oriented paths/tools to local shell and editing behavior. Skills orchestrate an agent-driven workflow, writing project-local generated artifacts rather than executing a central service. Key compatibility and dependency definitions:

• AGENTS.md

• skills/common/skill-dependencies.yaml

• skills/product/common/skill-dependencies.yaml

Python 3.9+ supports hooks, migration extractors, and terminal dashboards; Node.js 18+ is optional for Mermaid rendering.

Product-to-Architecture Pipeline

The product plugin turns an early product idea into validated requirements and hands off to architecture design. Its main stages are vision/scope and assumption validation, UX/domain/API/data derivation, then SLA/NFR synthesis. The dependency boundary is /architect:define-requirements, which consumes product outputs as implementation-design inputs.

• skills/product/start/SKILL.md

• skills/product/design-architecture/SKILL.md

• skills/define-requirements/SKILL.md

Architect Analysis and Design Pipeline

The architect plugin supports legacy assessment and greenfield system design. Its core flow is: investigate/analyze existing or required system behavior; evaluate maturity and DDD fitness; redesign domains; design microservices, data layer/ScalarDB, and APIs; run multi-perspective reviews; consolidate reports. The formal greenfield sequencing is documented in:

• workflow/greenfield/00_workflow_overview.md

• workflow/greenfield/01_requirements_analysis.md

• skills/pipeline/SKILL.md

Reports, generated code, and workflow state are intentionally separated into target-project reports/, generated/, and work/ directories.

ScalarDB Design and Knowledge Boundary

ScalarDB-specific skills provide schema, transaction, configuration, CRUD/JDBC, scaffolding, migration, and code-review guidance. Decisions are constrained by edition/version-aware official knowledge rather than generic advice. The knowledge bundle is a git submodule at knowledge/okf-scalardb-scalardl, with update lifecycle managed by:

• skills/design-scalardb/SKILL.md

• skills/model/SKILL.md

• rules/okf-knowledge-bundle.md

This boundary covers ScalarDB, ScalarDB Saga, and ScalarDL APIs, transaction patterns, and version-sensitive configuration.

Generation, Delivery, and External Integrations

Post-design code generation is a manual extension tier: implementation specs feed test specs, Spring Boot + ScalarDB code, infrastructure code, and documentation. Generated scaffolds stay disposable under generated/; backlog delivery instead edits the target repository’s real source tree and uses GitHub or GitLab issues/PRs/MRs as the merge-control boundary.

• skills/design-implementation/SKILL.md

• skills/generate-scalardb-code/SKILL.md

• skills/deliver-backlog/SKILL.md

Optional infrastructure/services include Kubernetes, Terraform, Helm, Docker Compose, GitHub/GitLab, Serena MCP for AST analysis, Context7 for current documentation, and Oracle/MySQL/PostgreSQL connections for migration analysis.

Observability and Workflow State

Terminal dashboards derive status, dependencies, stale phases, and token-cost reporting from workflow artifacts. Hooks validate generated front matter and Mermaid, while token usage can be recorded during agent runs.

• tools/nexus-status.sh

• tools/lib/pipeline_status_data.py

• hooks/record_token_usage.py