lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/CLAUDE.md
Lei Chen e4af0cac73 Phase 0: scheduleragent + mcp-server read-only agent framework 
Complete the natural-language scheduler agent's Phase 0 read-only pipeline:

Task #2 (API Key auth mechanism):
- New store/apikey.go: APIKey store (hash, validate, expiry)
- controllers/apikey.go: GenerateAPIKey finally persists + registers RBAC role
- controllers/auth.go: GetUsernameFromToken recognizes xce_ak_ prefix
- middleware/validatehandler.go: isValidToken handles API Key
- config/rbac.yaml: mcp_readonly role (view-only permissions)
- 6 new test files covering unit + integration full-chain

Task #3 (schedulerclient Go library):
- types.go: URM types (URMJob/URMQueue/URMNode/JobStatus/Metrics)
- client.go: read-only Client interface (6 methods)
- httpclient.go: resty-based HTTP implementation
- statusmap.go + _test.go: TDD status mapping (33 tests)

Task #4 (mcp-server binary):
- cmd/main.go: entry, reads XCE_API_URL/XCE_API_KEY, registers 6 MCP tools
- internal/app.go: tool handlers wiring schedulerclient to MCP stdio
- Uses github.com/mark3labs/mcp-go@v0.57.0 for stdio transport

All: go vet clean, go build clean, schedulerclient 33/33 tests pass.
mcp-server binary ~11MB arm64, CGO_ENABLED=0.

Architecture:
  Claude Code --stdio--> mcp-server --HTTP--> apiserver REST API --cgo--> C backend

Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-30 11:16:36 +08:00

6 KiB
Raw Blame History

OpenWolf

@.wolf/OPENWOLF.md

This project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.

XCE Cluster Management System

Project Overview

XCE is an HPC cluster management system — Go API/CLI tier fronting C daemons (controller, worker, scheduler). Full context in .kiro/steering/product.md.

Engineering Guide

For details on any topic below, read the corresponding steering file in .kiro/steering/. CLAUDE.md provides pointers, not duplicates.

Topic Steering File
Project purpose, HA phases, design decisions product.md
Technology stack, build systems, key decisions tech.md
Directory layout, naming conventions, test org structure.md
Build commands, Nix flake, deploy, AppImage build-deployment.md
REST handler pattern, daemon opcodes, Cap'n Proto api-standards.md
HA protocol, async I/O, Raft election, heartbeat ha-async-io.md
TDD rules, C + Go test patterns, coverage targets testing.md
Error handling: Go ReturnError, C errnox, zap logging error-handling.md
RBAC, JWT, auth backends, input validation, secrets security.md

Key Rules (from steering — summarized for quick reference)

  • TDD mandatory: red → green → refactor; test in testsuite/ before C changes, _test.go before Go changes
  • Async I/O: never block in vtask handlers; delaymgr for blocking ops. xce_request/xce_reply are always non-blocking
  • Connections are long-lived: closing signals RDHUP failover. Inbound connections are vote-only; outbound carry all state push
  • Middleware chain (non-negotiable): WhitelistURL → WhitelistIP → RateLimit → JWT → CORS → RBAC
  • Error pattern: ReturnError(code, msg, nil); return — early return on every error
  • Build: /xce-build [component] — debug + ASAN + tests. See build-deployment.md for full commands

Key Files

  • src/frontend/Makefile — primary build/test orchestration
  • src/frontend/apiserver/cmd/main.go — server startup, init sequence
  • src/frontend/apiserver/router/routers.go — all routes and middleware chain
  • src/frontend/apiserver/controllers/rbac_check.go — RBAC loading and enforcement
  • src/frontend/apiserver/config/rbac.yaml — role/permission definitions
  • src/frontend/apiserver/config/auth.yaml — auth provider selection

Subdirectory Guidelines

  • src/frontend/ — See src/frontend/CLAUDE.md
  • src/controller/ — See src/controller/CLAUDE.md
  • src/worker/ — See src/worker/CLAUDE.md
  • src/scheduler/ — See src/scheduler/CLAUDE.md
  • src/lib/ — See src/lib/CLAUDE.md
  • src/frontend/schedulerclient/, src/frontend/mcp-server/ — Phase 0 已完成（2026-07-26）。schedulerclient 是独立 Go library 提供只读 Client interface + resty HTTP 实现（33 单测）。mcp-server 是 MCP stdio 二进制（github.com/mark3labs/mcp-go@v0.57.0），通过 schedulerclient 调用 apiserver REST API，暴露 6 个只读 MCP Tool。Pure Go, CGO_ENABLED=0。总体架构与分阶段计划见根目录 CLAUDE.md（"Unified Scheduler Agent Framework"）。

Agentic SDLC and Spec-Driven Development

Kiro-style Spec-Driven Development on an agentic SDLC

Project Context

Paths

  • Steering: .kiro/steering/
  • Specs: .kiro/specs/

Steering vs Specification

Steering (.kiro/steering/) - Guide AI with project-wide rules and context Specs (.kiro/specs/) - Formalize development process for individual features

Active Specifications

  • Check .kiro/specs/ for active specifications
  • Use /kiro-spec-status [feature-name] to check progress

Development Guidelines

  • Think in English, generate responses in English. All Markdown content written to project files (e.g., requirements.md, design.md, tasks.md, research.md, validation reports) MUST be written in the target language configured for this specification (see spec.json.language).

Minimal Workflow

  • Phase 0 (optional): /kiro-steering, /kiro-steering-custom
  • Phase 1 (Specification):
    • /kiro-spec-init "description" — initialize spec scaffold
    • /kiro-spec-quick "description" — fast single-pass spec (requirements + design + tasks, no approval gates)
    • /kiro-spec-batch — generate specs for all features in a roadmap in parallel
    • /kiro-spec-requirements {feature}
    • /kiro-validate-gap {feature} (optional: for existing codebase)
    • /kiro-spec-design {feature} [-y]
    • /kiro-validate-design {feature} (optional: design review)
    • /kiro-spec-tasks {feature} [-y]
  • Phase 2 (Implementation): /kiro-impl {feature} [tasks]
    • /kiro-validate-impl {feature} (optional: after implementation)
    • /kiro-verify-completion {feature} — validate all acceptance criteria are met
  • Debugging: /kiro-debug {feature} — systematic debugging with spec context
  • Code review: /kiro-review — review implementation against spec requirements
  • Progress check: /kiro-spec-status {feature} (use anytime)

Development Rules

  • 3-phase approval workflow: Requirements → Design → Tasks → Implementation
  • Human review required each phase; use -y only for intentional fast-track
  • Use /kiro-spec-quick for small, well-understood features; full workflow for anything touching HA/persistence/RBAC
  • Keep steering current and verify alignment with /kiro-spec-status
  • Follow the user's instructions precisely, and within that scope act autonomously: gather the necessary context and complete the requested work end-to-end in this run, asking questions only when essential information is missing or the instructions are critically ambiguous.

Steering Configuration

  • Load entire .kiro/steering/ as project memory — all .md files are authoritative
  • Core: product.md, tech.md, structure.md
  • Custom: testing.md, error-handling.md, security.md, ha-async-io.md, api-standards.md, build-deployment.md
  • Add new custom files via /kiro-steering-custom; sync existing via /kiro-steering