diff --git a/.agents/skills/unidesk-oa/SKILL.md b/.agents/skills/unidesk-oa/SKILL.md new file mode 100644 index 00000000..d56715fe --- /dev/null +++ b/.agents/skills/unidesk-oa/SKILL.md @@ -0,0 +1,41 @@ +--- +name: unidesk-oa +description: UniDesk/HWLabOA project-management operating skill. Use when the user mentions HWLabOA, OA docs, total project specification, master plan, major project/direction/topic/subtopic hierarchy, task book, implementation plan, testing specification, phase report, project drift, or GitHub issue trees for HWLAB Cloud M1 / UniDesk / AgentRun cross-repo project governance. +--- + +# UniDesk OA + +Use this skill to keep HWLAB Cloud M1 project management centered on a stable master specification and a linked GitHub issue hierarchy. + +## Repositories + +- HWLabOA source of truth: `/root/HWLabOA` (`../HWLabOA` from `/root/unidesk`), remote `git@github.com:notLabyet/HWLabOA.git`, branch `main`. +- UniDesk control/tooling repo: `/root/unidesk`, remote `git@github.com:pikasTech/unidesk.git`, branch `master`. +- Before editing HWLabOA docs, run `git status --short --branch` and `git pull --ff-only origin main` in `/root/HWLabOA`. +- Before using UniDesk GitHub CLI or editing this skill, run `git status --short --branch` and `git pull --ff-only origin master` in `/root/unidesk`. + +## Operating Model + +- Treat HWLabOA Markdown as the durable specification source of truth. +- Treat GitHub issues as the execution control plane: hierarchy, status, discussion, cross-repo references, PR linkage, and closeout evidence. +- Do not let daily reports become the master plan. Phase reports summarize movement against the master spec; they do not define the center by themselves. +- When a task lacks a parent direction, acceptance criteria, or original validation entry, classify it as planning/investigation before turning it into implementation work. + +## Workflow + +1. For planning questions, read `references/project-planning.md`. +2. For creating or updating master specs or issue bodies, read `references/templates.md`. +3. When writing GitHub issues/PR comments, also use `unidesk-gh`; all writes must go through `bun scripts/cli.ts gh ...` from `/root/unidesk`. +4. When editing long-lived HWLabOA project docs, keep stable planning content in master/spec files and use phase-report docs only for dated summaries. + +## Required Hierarchy + +Use this task tree unless the user gives a stricter one: + +- L0: Major project / master specification. +- L1: Direction. +- L2: Topic. +- L3: Subtopic / validation slice. +- L4: Execution task / PR / CaseRun / smoke / doc closeout. + +Every non-trivial issue should state its parent links, target branch/lane, acceptance criteria, validation entry, and closeout writeback target. diff --git a/.agents/skills/unidesk-oa/agents/openai.yaml b/.agents/skills/unidesk-oa/agents/openai.yaml new file mode 100644 index 00000000..a7e9ec40 --- /dev/null +++ b/.agents/skills/unidesk-oa/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "UniDesk OA" + short_description: "Manage HWLabOA master specs and issue hierarchies." + default_prompt: "Use this skill to plan HWLabOA project structure, master specifications, and linked GitHub issue trees." diff --git a/.agents/skills/unidesk-oa/references/project-planning.md b/.agents/skills/unidesk-oa/references/project-planning.md new file mode 100644 index 00000000..f22d647f --- /dev/null +++ b/.agents/skills/unidesk-oa/references/project-planning.md @@ -0,0 +1,138 @@ +# UniDesk OA Project Planning + +## Purpose + +HWLAB Cloud M1 needs a project control structure that prevents local issue/PR work from drifting away from the center. Use a research-project style hierarchy: + +- Major project: overall mission, product goal, delivery boundary. +- Direction: stable workstream under the major project. +- Topic: concrete program of work inside a direction. +- Subtopic: bounded validation slice with explicit acceptance criteria. +- Execution task: issue, PR, CaseRun, smoke, deployment, or document closeout. + +## Document And Issue Split + +Use documents for durable truth: + +- Master specification. +- Direction implementation plans. +- Test/validation specifications. +- Decision rationale. +- Stable acceptance criteria. + +Use issues for execution state: + +- Current owner/status. +- Discussion and evidence. +- Cross-repo references. +- PR and commit linkage. +- Runtime trace/session/job IDs. +- Closeout comments. + +Do not store the only copy of a stable requirement in an issue comment. If the requirement is long-lived, distill it into HWLabOA and link it from the issue. + +## Suggested HWLabOA Structure + +For HWLAB Cloud M1, keep the durable docs under: + +```text +/root/HWLabOA/Project Management/[EPIC001][HWLab][PRJ002][CLOUD-M1]/ +``` + +Recommended files: + +```text +SPEC-CLOUD-M1-MASTER.md # L0 master specification and issue tree index +SPEC-CLOUD-M1.md # Existing dated/phase material, can link to master +PLAN-CLOUD-M1-DIRECTIONS.md # L1 direction implementation plans, optional +TEST-CLOUD-M1-VALIDATION.md # Cross-direction validation matrix, optional +``` + +Prefer one master file first. Split only when the master becomes too large or when a section has independent lifecycle and review needs. + +## L0-L4 Rules + +### L0 Major Project + +The L0 item defines: + +- Mission and non-goals. +- Current center of gravity. +- Product surfaces. +- Direction list. +- Global acceptance criteria. +- Cross-repo source truth. +- Issue hierarchy index. +- Drift indicators. + +There should normally be one L0 GitHub issue and one L0 master spec document. + +### L1 Direction + +Each direction must answer: + +- Which part of the L0 goal it serves. +- What completion means. +- Which repos/branches/lanes are involved. +- Which original user/runtime entry validates it. +- Which L2 topics currently matter. + +Typical HWLAB Cloud M1 directions: + +- Embedded cloud-development loop: ARM2D, PLC/ConStart, CaseRun. +- Multi-user cloud platform: auth, user-billing, usage, collaboration. +- HWPOD hardware access: specs, board-comm, device nodes, Keil/D601 bridge. +- AgentRun execution substrate: runner/session/resource/recovery. +- UniDesk control plane: trans, GitHub, Sub2API, YAML ops, D601/G14/PK01. +- Cloud Web/product surface: v0.3 Vue parity, workbench, admin, usage, access. + +### L2 Topic + +Topics should be concrete enough to plan and close: + +- PLC 71-FREQ CaseRun production loop. +- ARM2D upstream integration. +- D601 v0.3 user-billing and usage summary. +- React to Vue parity closeout. +- Sub2API Codex pool failover stability. + +### L3 Subtopic + +Subtopics are validation slices. They must define a single acceptance path: + +- A CaseRun with expected artifact. +- A CLI smoke with target lane. +- A Web original-entry check. +- A deployment/control-plane action with status evidence. +- A document decision with linked references. + +### L4 Execution Task + +Execution tasks map to one PR, one runtime validation, one CaseRun, or one closeout document update. They should not become mini-epics. + +## Drift Controls + +Flag a task as drift-risk when: + +- It has no L1/L2 parent. +- It improves tooling but does not remove a named blocker. +- It changes a runtime/control plane without an original validation entry. +- It expands frontend parity without tying back to Code Agent/HWPOD/user workflow. +- It improves observability but no downstream decision depends on the new signal. +- It keeps ARM2D/PLC evidence polishing without a new real upstream or board-facing case. + +When drift-risk is found, either attach it to a parent and acceptance criterion, or reclassify it as investigation. + +## Phase Report Rule + +Every phase report should include: + +- Time window and timezone. +- Source scope: repos/issues/PRs checked. +- Movement against L0/L1 goals. +- Completed validation evidence. +- Open blockers. +- Drift assessment. +- Next validation-oriented target. + +Avoid reporting issue volume as progress. Report only changes that move a direction toward its acceptance criteria. diff --git a/.agents/skills/unidesk-oa/references/templates.md b/.agents/skills/unidesk-oa/references/templates.md new file mode 100644 index 00000000..4b599381 --- /dev/null +++ b/.agents/skills/unidesk-oa/references/templates.md @@ -0,0 +1,189 @@ +# UniDesk OA Templates + +## L0 Master Specification Skeleton + +```markdown +# HWLAB Cloud M1 Master Specification + +## 1. Mission + +One paragraph describing the product and research objective. + +## 2. Non-Goals + +- ... + +## 3. Current Center + +- Current primary validation line: +- Secondary validation line: +- Explicitly paused/deferred line: + +## 4. Direction Tree + +| Level | Title | GitHub issue | Spec section | Current status | +| --- | --- | --- | --- | --- | +| L1 | Embedded cloud-development loop | TBD | ... | ... | +| L1 | Multi-user cloud platform | TBD | ... | ... | +| L1 | HWPOD hardware access | TBD | ... | ... | +| L1 | AgentRun execution substrate | TBD | ... | ... | +| L1 | UniDesk control plane | TBD | ... | ... | +| L1 | Cloud Web/product surface | TBD | ... | ... | + +## 5. Global Acceptance Criteria + +- ... + +## 6. Direction Details + +### L1: Embedded cloud-development loop + +- Goal: +- Non-goal: +- Current topics: +- Acceptance criteria: +- Validation entries: +- Open blockers: + +## 7. Issue Hierarchy Index + +- L0: +- L1: +- L2: +- L3/L4: + +## 8. Drift Rules + +- ... + +## 9. Phase Report Links + +- ... +``` + +## L0 Issue Body + +```markdown +目标合并分支: 不适用 +原因: 本 issue 是 HWLAB Cloud M1 总项目管理锚点，代码变更由下级 issue/PR 承载。 + +总规格文档: + +## 项目中心 + +- 当前主线: +- 当前非主线但保留: +- 暂停/等待: + +## L1 方向 + +- [ ] #... 方向A: +- [ ] #... 方向B: +- [ ] #... 方向C: + +## 全局验收 + +- ... + +## 偏离判定 + +- 无上级方向的任务不得直接作为实现任务推进。 +- 无原入口验收的任务不得关闭。 +- 日报/阶段报告只总结，不替代总规格。 + +## 回写规则 + +- 下级 issue 关闭时必须评论回写到对应 L1。 +- L1 阶段完成时必须回写本 issue，并更新 HWLabOA 总规格。 +``` + +## L1 Direction Issue Body + +```markdown +目标合并分支: 不适用 +原因: 本 issue 是方向级项目管理锚点，代码变更由下级 topic/subtopic issue 承载。 + +上级总项目: #... +总规格文档: + +## 方向目标 + +... + +## 边界 + +- In scope: +- Out of scope: + +## L2 课题 + +- [ ] #... + +## 验收标准 + +- 原入口: +- Runtime/lane: +- Evidence: + +## 当前阻塞 + +- ... + +## 回写规则 + +- 下级 L2/L3 完成后评论回写本 issue。 +- 方向状态变化后更新 L0 issue 和 HWLabOA 总规格。 +``` + +## L2/L3 Execution Issue Header + +```markdown +目标合并分支: + +上级总项目: #... +所属方向: #... +所属课题: #... +规格文档: + +## 目标 + +... + +## 验收入口 + +- CLI/Web/CaseRun: +- Target lane/node: +- Required evidence: + +## 完成后回写 + +- [ ] 评论回写所属课题 +- [ ] 评论回写所属方向 +- [ ] 如稳定规则变化，更新 HWLabOA 总规格 +``` + +## Phase Report Section + +```markdown +## YYYY年M月D日阶段报告（北京时间） + +- 统计口径 + - 时间窗口: + - 核对仓库: + - issue/PR 范围: + +- 对总目标的移动 + - ... + +- 已完成验收 + - ... + +- 未完成/跨日 + - ... + +- 偏离评估 + - ... + +- 下一阶段目标 + - ... +```