From 4376618c17d8312145585788cb904902acb9c0a9 Mon Sep 17 00:00:00 2001 From: AkiKurisu <2683987717@qq.com> Date: Wed, 15 Jul 2026 23:56:23 +0800 Subject: [PATCH 1/2] refactor: split dotcraft-dev to two plugins --- .craft/plugins/marketplace.json | 12 + .../dotcraft-dev/.craft-plugin/plugin.json | 8 +- .../dotcraft-dev/skills/dev-guide/SKILL.md | 67 ++---- .../dotcraft-dev/skills/docs-guide/SKILL.md | 48 ++-- .../skills/docs-guide/agents/openai.yaml | 2 +- .../docs-guide/references/project-profile.md | 20 +- .../skills/feature-workflow/SKILL.md | 221 ------------------ .../feature-workflow/agents/openai.yaml | 4 - .../skills/release-draft/SKILL.md | 18 +- .../skills/release-draft/agents/openai.yaml | 2 +- .../dotcraft-dev/skills/ui-prototype/SKILL.md | 97 -------- .../skills/ui-prototype/agents/openai.yaml | 4 - .../.craft-plugin/plugin.json | 21 ++ .../assets/harness-workflow.svg | 11 + .../skills/feature-workflow/SKILL.md | 190 +++++++++++++++ .../feature-workflow/agents/openai.yaml | 4 + .../skills/svg-design/SKILL.md | 0 .../skills/svg-design/agents/openai.yaml | 0 .../references/svg_design_checklist.md | 0 .../svg-design/scripts/preview_svgs.mjs | 0 .../skills/ui-prototype/SKILL.md | 99 ++++++++ .../skills/ui-prototype/agents/openai.yaml | 4 + 22 files changed, 396 insertions(+), 436 deletions(-) delete mode 100644 plugins/dotcraft-dev/skills/feature-workflow/SKILL.md delete mode 100644 plugins/dotcraft-dev/skills/feature-workflow/agents/openai.yaml delete mode 100644 plugins/dotcraft-dev/skills/ui-prototype/SKILL.md delete mode 100644 plugins/dotcraft-dev/skills/ui-prototype/agents/openai.yaml create mode 100644 plugins/harness-workflow/.craft-plugin/plugin.json create mode 100644 plugins/harness-workflow/assets/harness-workflow.svg create mode 100644 plugins/harness-workflow/skills/feature-workflow/SKILL.md create mode 100644 plugins/harness-workflow/skills/feature-workflow/agents/openai.yaml rename plugins/{dotcraft-dev => harness-workflow}/skills/svg-design/SKILL.md (100%) rename plugins/{dotcraft-dev => harness-workflow}/skills/svg-design/agents/openai.yaml (100%) rename plugins/{dotcraft-dev => harness-workflow}/skills/svg-design/references/svg_design_checklist.md (100%) rename plugins/{dotcraft-dev => harness-workflow}/skills/svg-design/scripts/preview_svgs.mjs (100%) create mode 100644 plugins/harness-workflow/skills/ui-prototype/SKILL.md create mode 100644 plugins/harness-workflow/skills/ui-prototype/agents/openai.yaml diff --git a/.craft/plugins/marketplace.json b/.craft/plugins/marketplace.json index 6bf9db2..dc2c600 100644 --- a/.craft/plugins/marketplace.json +++ b/.craft/plugins/marketplace.json @@ -147,6 +147,18 @@ "authentication": "ON_INSTALL" }, "category": "Productivity" + }, + { + "name": "harness-workflow", + "source": { + "source": "local", + "path": "./plugins/harness-workflow" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Engineering" } ] } diff --git a/plugins/dotcraft-dev/.craft-plugin/plugin.json b/plugins/dotcraft-dev/.craft-plugin/plugin.json index f00807e..704241a 100644 --- a/plugins/dotcraft-dev/.craft-plugin/plugin.json +++ b/plugins/dotcraft-dev/.craft-plugin/plugin.json @@ -1,19 +1,19 @@ { "schemaVersion": 1, "id": "dotcraft-dev", - "version": "0.1.0", + "version": "0.2.0", "displayName": "DotCraft Dev", "description": "Development plugin for working on DotCraft itself.", "capabilities": ["skill"], "skills": "./skills/", "interface": { "displayName": "DotCraft Dev", - "shortDescription": "DotCraft development guidance, workflows, docs standards, UI prototyping, and SVG support.", - "longDescription": "A DotCraft development plugin for contributors working on DotCraft itself. It bundles repository guidance, feature workflow planning, documentation writing standards, Desktop UI prototyping, and SVG asset design skills under one shared DotCraft Developer logo.", + "shortDescription": "DotCraft development guidance, documentation standards, and release drafting.", + "longDescription": "Product-specific guidance for contributors working on DotCraft itself, including repository development norms, localized documentation standards, and evidence-based GitHub release drafting.", "developerName": "DotHarness", "category": "Engineering", "capabilities": ["Skill"], - "defaultPrompt": "Use the bundled DotCraft development skills for repository guidance, feature workflow planning, documentation writing, Desktop UI prototyping, or SVG asset design.", + "defaultPrompt": "Help me make this change to DotCraft while following the project's development, documentation, and release conventions.", "brandColor": "#2458F7", "composerIcon": "./assets/dotcraft-developer.svg", "logo": "./assets/dotcraft-developer.svg" diff --git a/plugins/dotcraft-dev/skills/dev-guide/SKILL.md b/plugins/dotcraft-dev/skills/dev-guide/SKILL.md index 0d7fd85..6f6dded 100644 --- a/plugins/dotcraft-dev/skills/dev-guide/SKILL.md +++ b/plugins/dotcraft-dev/skills/dev-guide/SKILL.md @@ -1,13 +1,13 @@ --- name: dotcraft-dev-guide -description: Development workflow and project-specific norms for DotCraft. Use when changing protocol behavior, or shipping user-facing features. Covers spec-first workflow, testing rules and bilingual docs. +description: Development workflow and project-specific norms for DotCraft. Use when changing protocol behavior or shipping user-facing features. Covers spec-first workflow, testing, localization, and documentation responsibilities. --- # DotCraft Development Guide Project-specific workflow and norms for DotCraft. -For generic C#/Rust/React style, follow each ecosystem's standard conventions. -For repo orientation, read `CLAUDE.md`. +For general language and framework style, follow the relevant ecosystem conventions. +For repo orientation, read the applicable `AGENTS.md` files. ## Development Workflow @@ -19,7 +19,7 @@ If a proposed change conflicts with an existing spec, resolve the spec-level con ### Steps 1. **Plan**: Search the codebase for similar features before adding new abstractions. -2. **Implement**: Follow the project-specific norms below. Add XML docs for public C# APIs. Update user-facing docs in both languages when behavior changes. +2. **Implement**: Follow the project-specific norms below. Add XML docs for public C# APIs. Update affected user-facing docs and localized content when behavior changes. 3. **Test**: Follow the testing rules below. 4. **Verify**: Confirm changes conform to the relevant spec and docs/examples are in place. @@ -31,64 +31,23 @@ Mode-specific tool removal is appropriate only when the mode represents a genuin ### Testing Rules -Tests are required for: +Add tests when an observable contract changes, especially for protocol-dependent behavior and complex multi-step flows or state machines. Pure visual polish, copy changes, trivial refactors, and fixes that do not change an observable contract do not require new tests. -- Protocol-dependent code (JSON-RPC, wire format, session/appserver protocol): add conformance tests aligned with the spec. -- Complex multi-step flows or state machines: cover key paths and edge cases. +A meaningful test catches a real regression without duplicating existing coverage or testing language, framework, or private implementation details. Prefer assertions on public behavior, state, persisted data, wire payloads, and user-visible output. Use real temporary dependencies or small fakes instead of extensive mocking unless an interaction is itself the contract. -Tests are not required for: - -- Small bug fixes that do not change an observable contract. -- Pure UI polish (layout, styling, copy tweaks) in desktop or TUI. -- Trivial refactors with no behavior change. - -A test is meaningful only when (applies to C# xUnit and TypeScript tests equally): - -- It catches a real regression, not language semantics, trivial getters/setters, or framework internals. -- It is not redundant with existing coverage; check before adding. -- It does not merely restate implementation details via excessive mocking; prefer state/output assertions unless interaction itself is the contract. -- It is not written just to inflate coverage numbers. - -Desktop frontend tests: - -- Test behavior, not static styling. Cover user-visible output, accessibility names, - enabled/disabled state, navigation, store updates, IPC calls, serialization, and - data mapping. -- Do not assert one-to-one visual implementation details such as CSS variables, - colors, borders, shadows, spacing, radii, widths/heights, token values, source - string snippets, or class names whose only purpose is styling. -- Keep style-related assertions only when the style is the functional contract, - such as computed positions from a drag/drop or popover placement algorithm, - ANSI color parsing, virtualized geometry, or resize behavior. -- Prefer short interaction tests over source/CSS guards. If a UI change is pure - polish, document it or verify it manually instead of adding test volume. - -DotCraft.Core C# xUnit tests: - -- Test observable behavior through public APIs, persisted state, wire payloads, or user-visible results; do not test private implementation shape. -- When using TDD, work in vertical slices: write one behavior test, make the smallest useful implementation pass, then repeat. -- For protocol, session, and persistence behavior, prefer real temp stores/services and small fakes over mocks; use interaction assertions only when the interaction is the contract. -- Do not add tests for trivial formatters, getters, record equality, text passthrough, description/prompt wording, framework behavior, or coverage inflation. -- Use theories to consolidate repetitive variants only when each row protects a meaningful externally visible case. - -Pre-commit: run the relevant full suites for touched areas (`dotnet test` for C#, and corresponding `npm test`/`cargo test` where applicable). Do not commit with known failures. +- **Frontend**: Test behavior such as accessibility, state, navigation, IPC, serialization, and data mapping. Do not assert styling details unless geometry or visual state is the functional contract; verify pure polish manually. +- **Core C#**: Test through public APIs and observable results. Skip trivial formatters, getters, record equality, text passthrough, prompt wording, and framework behavior. ### Language Preference +Before changing localized UI or documentation, inspect the repository's current locale configuration, catalogs, and existing mirrors. Treat those as the source of truth and update every currently supported locale; do not rely on a locale list embedded in this skill. + - **Code comments**: English -- **Desktop UI strings**: Desktop owns UI localization. Localize for all supported app locales — `en`, `zh-Hans`, `ja`, `ko`, `es`, `fr`, `de` (the source of truth is `desktop/src/shared/locales/types.ts`). This applies to message catalogs and to data-driven UI text such as plugin/extension descriptor `localizedLabel`; provide every supported locale, missing ones fall back to the base string. +- **UI strings**: The client owns UI localization. Update every locale discovered from the current source of truth, including message catalogs and data-driven UI text such as localized plugin or extension labels. - **C# runtime/UI-adjacent messages**: Do not add UI localization state or server-side translation catalogs. C# should emit stable machine-readable keys/codes plus English fallback text (`FallbackText` for CLI/server fallback copy). Desktop owns UI localization. - **Protocol-visible system messages**: New client-visible notifications and errors must provide a stable key/code, structured params where useful, and an English fallback. User text, model output, and raw tool output must pass through unchanged. -- **Docs vs UI**: Documentation (`docs/`) is bilingual (English + Chinese) only; UI strings cover all supported locales above. +- **Documentation**: Discover the currently supported documentation locales and mirror structure before writing, then update every affected version in the same change. ## Documentation Guidelines -DotCraft documentation lives under `docs/` as a VitePress documentation site. -For the full documentation writing standard — audience/purpose routing, per-archetype page templates, voice rules, and the bilingual style guide — use the `dotcraft-docs-guide` skill. The essentials: - -When creating or updating documentation: - -- Provide all documentation in both Chinese and English. -- Consider whether the documentation location fits the existing site structure. When inserting new documentation, ask the user where it should go unless the user has already approved a location. -- Keep documentation concise and current. Do not include historical explanations, such as old-version migration rationale or why legacy behavior existed. -- Keep the style user-friendly. Avoid excessive code references unless the document is explicitly providing code examples, such as SDK documentation. +Use `dotcraft-docs-guide` for audience routing, page structure, voice, localization, and site conventions. Before writing, inspect the current documentation structure and supported locales. Place new pages with the appropriate audience, ask only when placement is ambiguous, and document current behavior without historical rationale. diff --git a/plugins/dotcraft-dev/skills/docs-guide/SKILL.md b/plugins/dotcraft-dev/skills/docs-guide/SKILL.md index 77ea0fd..45b72fb 100644 --- a/plugins/dotcraft-dev/skills/docs-guide/SKILL.md +++ b/plugins/dotcraft-dev/skills/docs-guide/SKILL.md @@ -1,17 +1,13 @@ --- name: dotcraft-docs-guide -description: Standards for writing and editing DotCraft documentation under `docs/` (the bilingual VitePress site). Use whenever creating or revising a docs page — overview/getting-started, a feature page, an architecture/concept explainer, an SDK/API/CLI/protocol reference, or a how-to — or when deciding the right tone, structure, and code density for a page. Trigger this even when the user just says "write docs for X", "add a page about Y", "the docs for Z read badly", or "make this doc more user-friendly", and especially when a page must serve end users vs. developers differently. Does not cover GitHub release notes (use release-draft) or in-code XML/JSDoc comments. +description: Guidance for writing and editing DotCraft documentation for users and developers, including localized content. Does not cover release notes or code comments. --- # Documentation Guide -A reusable standard for writing product documentation. The single most important decision for any page is **who it is for** and **what job it does** — that choice drives tone, structure, code density, and what you leave out. Most weak docs fail because they mix a beginner's "show me" with a developer's "give me the contract" on one page. This skill keeps those separate. +The key decision for every page is **who it is for** and **what job it does**. That choice determines tone, structure, code density, and what to omit. -The principles here are project-agnostic. Everything specific to *this* repository — doc framework, section layout, languages, file paths, callout syntax, protected product terms — lives in `references/project-profile.md`. Read that profile first; to reuse this skill on another project, replace only that file. (For the broader DotCraft dev workflow, see the `dotcraft-dev-guide` skill.) - -## When to use - -Use this when you write or revise any documentation page, or user-facing README copy. Before drafting prose, settle the two questions in Step 1 — they are the whole game. +Repository-specific details — doc framework, section layout, localization, paths, syntax, and terminology examples — live in `references/project-profile.md`. Read it first and verify changeable details against the current repository. Use `dotcraft-dev-guide` for the broader development workflow. ## Step 1 — Decide audience and purpose @@ -35,7 +31,7 @@ Every page answers two questions before you write a sentence. If you can't name one cell in each table, the page has no focus yet — split it. A feature page that drifts into protocol field tables should hand that off to a reference page and link to it. -**Routing examples:** a "Getting Started" page = end user × tutorial → warm, one path, almost no code internals. A protocol page = developer × reference → neutral, exhaustive, table-driven. A "what is feature X" page = end user × explanation → friendly concept page with a diagram, light on code. +**Illustrative routing examples (e.g., not an exhaustive mapping):** a "Getting Started" page = end user × tutorial → warm, one path, almost no code internals. A protocol page = developer × reference → neutral, exhaustive, table-driven. A "what is feature X" page = end user × explanation → friendly concept page with a diagram, light on code. ## Step 2 — Match the voice to the reader @@ -57,7 +53,7 @@ The detailed mechanics — person, headings, capitalization, sentence length, co ## Step 3 — Use the right page template -Don't invent structure. Copy the matching skeleton from `references/page-templates.md` (quickstart, feature overview, how-to, concept/architecture, reference, troubleshooting) and fill it in. +Use the matching skeleton from `references/page-templates.md` (quickstart, feature overview, how-to, concept/architecture, or reference) rather than inventing a new structure. ## House conventions (apply to every page) @@ -70,32 +66,20 @@ These principles are universal; the exact syntax, paths, and terms for this repo - **End with a "Related docs" footer** of 2–5 sibling links. Assume the reader arrived from search; always give them a next step. Use relative links. - **Diagrams carry alt text**; reuse existing ones before drawing new. (Location: profile.) - **Stay current; no history.** Don't document old-version migration rationale or "why the legacy behavior existed." Describe how it works now. -- **Preserve product/brand terms exactly** — don't paraphrase them. (List: profile.) +- **Preserve established product and brand terms exactly.** The profile contains examples, not an exhaustive vocabulary; inspect current product UI, specs, code, and nearby docs for additional terms. - **If the project ships more than one language**, keep all versions structurally identical and edit them in the same change. (Languages + paths: profile.) ## What must NOT appear -Docs most often lose readers by *including* things that don't belong on the page — not by leaving things out. This is the most common failure mode. Before shipping a page, hunt these down and cut or relocate them. - -1. **Internal mechanics on a user or feature page.** Storage paths, config keys, tool/function schemas, state-machine enums, wire formats, class names. A feature page explains *what / why / when*; the instant one of these appears, replace it with a link to the reference page. *Smell: a "what is X" page whose first table exposes an internal storage path and data model the reader doesn't need.* - -2. **Architecture explained before the reader needs it.** Don't introduce internal subsystem names or "how it's built" in onboarding or a feature intro. Establish what it does and why first; defer the internals to the developer section and link. *Smell: a getting-started page that lectures on the execution engine right after the user's first action.* - -3. **Register whiplash within one page.** Swinging from marketing voice to spec voice leaves everyone unsure who the page is for. One audience per page; if two are genuinely needed, split and link. - -4. **Any term used before it's defined.** Internal nouns, acronyms, and load-bearing rules relied on before — or without ever — being explained. Define on first use or link to the definition, especially on the onboarding path. - -5. **Historical, migration, or compatibility rationale.** "previously…", "this used to…", "kept for compatibility", "older data isn't migrated". The reader can't act on it — it's changelog material. Describe only current, observable behavior. - -6. **Internal-only and spec-voice content.** Maintainer-only env flags, internal TODOs, and requirement phrasing ("the screen **should** open settings…"). Reference docs describe how the product behaves *to a consumer*, not how it ought to behave *to its own developers*. - -7. **Duplicated content that drifts.** The same comparison table or value-prop copied across pages — worse, with different labels in each — confuses instead of reinforcing. Single-source it on one page and link from the rest. - -8. **Unnatural, translated-feeling phrasing.** Quote-as-subject sentences, actor-hidden noun piles, and long enumerations crammed into one sentence where a list would read instantly. Read it aloud — if you wouldn't say it, rewrite it. - -9. **Load-bearing rules left implicit.** If a rule matters, state it once, plainly, as a rule — don't make the reader reverse-engineer it by diffing examples across pages. +Before shipping, remove or relocate: -10. **Troubleshooting, FAQ, or Q&A sections.** A small problem that keeps recurring means the guidance above it is too thin — strengthen that guidance so the problem doesn't arise, instead of bolting on an error→fix entry. A genuine bug belongs in the issue tracker, where it can be tracked and fixed, not frozen into a doc that quietly goes stale. When you remove a troubleshooting block, fold any load-bearing hint into the relevant step as positive guidance and cut the rest. +1. Internal mechanics or premature architecture on user-facing pages. +2. Mixed user and developer registers on one page. +3. Undefined terms, acronyms, or implicit load-bearing rules. +4. Historical, migration, compatibility-rationale, maintainer-only, or spec-voice content. +5. Duplicated content that should have one source of truth. +6. Unnatural translated phrasing or dense noun-heavy sentences. +7. Troubleshooting, FAQ, or Q&A sections. Fold essential prevention into the relevant guidance; track genuine bugs in the issue tracker. Worked before/after examples for each are in `references/style-and-mechanics.md` (§10). @@ -110,8 +94,8 @@ Before you call a page done: - [ ] Admonitions earn their place; no callout spam. - [ ] "Related docs" footer present with relative links. - [ ] No troubleshooting / FAQ / Q&A block — guidance gaps fixed inline, genuine bugs left to the issue tracker. -- [ ] Nothing from "What must NOT appear" is present — no internal mechanics on user pages, no premature architecture, no history/migration notes, no internal flags or spec-voice "should", no drifting duplicates, no undefined jargon. -- [ ] Product terms preserved; all project-profile conventions followed (languages in sync, callout/code syntax, asset location). +- [ ] Nothing from "What must NOT appear" remains. +- [ ] Established product terms are preserved, including relevant terms not listed in the profile; all current project-profile conventions are followed. - [ ] New page placed where its audience already lives — if unsure, ask before creating it. ## Reference files diff --git a/plugins/dotcraft-dev/skills/docs-guide/agents/openai.yaml b/plugins/dotcraft-dev/skills/docs-guide/agents/openai.yaml index a145a98..3195207 100644 --- a/plugins/dotcraft-dev/skills/docs-guide/agents/openai.yaml +++ b/plugins/dotcraft-dev/skills/docs-guide/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "DotCraft Docs Guide" - short_description: "Standards for writing DotCraft's bilingual docs by audience and purpose" + short_description: "Write and edit DotCraft documentation" default_prompt: "Use $dotcraft-docs-guide to write or revise DotCraft documentation with the right tone and structure for end users vs developers." diff --git a/plugins/dotcraft-dev/skills/docs-guide/references/project-profile.md b/plugins/dotcraft-dev/skills/docs-guide/references/project-profile.md index b9fead1..51bae5d 100644 --- a/plugins/dotcraft-dev/skills/docs-guide/references/project-profile.md +++ b/plugins/dotcraft-dev/skills/docs-guide/references/project-profile.md @@ -1,6 +1,6 @@ # Project Profile — DotCraft -This is the **only** project-specific file in the skill. `SKILL.md`, `page-templates.md`, and `style-and-mechanics.md` are portable writing guidance and reference this file for anything concrete (framework, file paths, languages, syntax, product terms). To reuse the skill on another project, replace **this file** and leave the rest intact. +This file records DotCraft-specific conventions and examples. Verify them against the current repository before writing; locale support and product terminology can evolve. ## Doc system @@ -15,12 +15,12 @@ This is the **only** project-specific file in the skill. `SKILL.md`, `page-templ Place a new page where its audience already lives. If unsure where it goes, ask before creating it. -## Languages (bilingual) +## Localized documentation -- Two languages only: English at `docs/.md`, Chinese mirror at `docs/zh/.md`. -- Keep structure, headings, links, code, admonitions, and images identical across both, and edit both in the same change. -- VitePress handles `/zh/` routing; internal links omit the locale prefix and the `.md` extension. -- Desktop UI strings are a separate, multi-locale system — out of scope here (see the `dotcraft-dev-guide` skill). +- Before editing, inspect the current VitePress locale configuration and existing page mirrors to discover every supported documentation locale and its path. +- Keep all localized versions structurally aligned: headings, links, code, admonitions, and images should match, and affected versions should be updated together. +- Follow the current locale routing and internal-link conventions found in the site configuration and nearby pages. +- UI localization is separate and is covered by `dotcraft-dev-guide`. ## Callouts / admonitions @@ -54,14 +54,14 @@ Group parallel examples with VitePress code-group, canonical order **TypeScript End every content page with a **Related docs** section: 2–5 relative links to sibling pages. -## Protected terms (don't paraphrase or translate) +## Protected terms (examples, not an exhaustive list) -`workspace`, `.craft/`, `Agent Teams`, `Mission`, `Team Leader`, `AppServer`, `Hub`, `Dreams`, `Souls`, `App Binding`, `Unified Session Core`. Code, commands, identifiers, and product names stay in English in both language versions. +Preserve established product terminology exactly. Examples (e.g.) include `workspace`, `.craft/`, `Agent Teams`, `Mission`, `Team Leader`, `AppServer`, `Hub`, `Dreams`, `Souls`, `App Binding`, and `Unified Session Core`. Before writing, inspect current UI copy, specs, code, and nearby docs for additional protected terms. Keep code, commands, identifiers, and product names unchanged unless the current project explicitly localizes them. ## Cross-platform shells The product is cross-platform: show `bash` first and a `powershell` alternative where commands differ (use `$null`, `$env:VAR` in PowerShell). -## Adapting this skill to another project +## Keeping this profile current -Replace this file with your project's profile. Cover: doc generator, section/audience layout, languages + file paths, callout syntax, code-tab syntax + language order, asset location, footer convention, and protected product terms. The portable files already point here for all of it. +Treat the entries above as guidance, not a closed inventory. When repository configuration or established usage disagrees with this file, follow the current repository and update the profile. diff --git a/plugins/dotcraft-dev/skills/feature-workflow/SKILL.md b/plugins/dotcraft-dev/skills/feature-workflow/SKILL.md deleted file mode 100644 index 46c9fc8..0000000 --- a/plugins/dotcraft-dev/skills/feature-workflow/SKILL.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -name: dotcraft-feature-workflow -description: Guides large DotCraft feature development from research and milestone planning through milestone specs, one-milestone-at-a-time implementation, and spec-based validation. Use when planning or delivering a substantial new DotCraft feature, a multi-milestone capability, or any request that should be designed before implementation. ---- - -# DotCraft Feature Workflow - -Use this skill for large new features or major capability expansions in DotCraft. - -The default stance is discussion-first, spec-before-code, one milestone at a time, and validation against the agreed milestone spec. - -## Core rules - -1. Do not jump straight into implementation for large features. -2. Discuss whether external reference research is needed before searching GitHub or cloning repositories. -3. Treat milestone specs as product and behavior contracts, not implementation design docs. -4. Implement only one milestone at a time unless the developer explicitly asks for a bundled delivery. -5. If implementation reality conflicts with the spec, stop and ask instead of silently changing scope. - -## Standard workflow - -### Phase 1: Scope and reference research - -Start by clarifying: - -- the feature goal -- who benefits from it -- what success looks like -- what is explicitly out of scope - -If existing examples or prior art may matter, discuss that with the developer first. - -When external reference research is approved: - -- inspect GitHub for relevant projects, modules, or design patterns -- clone candidate repositories into `references/` -- analyze them in detail for architecture, workflow, UX, and lifecycle ideas -- summarize the findings in the conversation by default - -Default artifact rule: - -- keep research summaries in chat unless the developer explicitly asks to persist them -- do not create a permanent research document by default - -Research output should capture: - -- the strongest reusable ideas -- patterns that fit DotCraft -- patterns that do not fit DotCraft -- open questions created by the research - -Soft gate: - -- after research and the first design direction, pause for confirmation when there are meaningful trade-offs, unresolved uncertainty, or major scope choices - -### Phase 2: Milestone outline - -Produce a milestone outline before writing milestone specs. - -Each milestone should have: - -- a short name -- the user or product goal -- the expected outcome at the end of the milestone -- key scope boundaries -- major dependencies or blockers - -Use a simple outline like this: - -```markdown -## Milestone Outline - -- M1: [name] - Goal: [...] - Expected outcome: [...] - Out of scope: [...] - Dependencies: [...] - -- M2: [name] - Goal: [...] - Expected outcome: [...] - Out of scope: [...] - Dependencies: [...] -``` - -This outline is the planning scaffold for the later `specs/` files. It does not need to contain implementation details. - -### Phase 3: Risk and feasibility review - -Once the milestone outline exists, discuss risks and technical difficulty with the developer. - -Review at least: - -- architecture pressure on existing modules -- compatibility or migration concerns -- UX complexity -- testing difficulty -- whether the milestone split is still realistic - -The goal is to decide whether the plan is feasible, not to design the final code yet. - -### Phase 4: Milestone spec authoring - -Write milestone spec files under `specs/`. - -Naming rule: - -- use numbered milestone files such as `feature-name-m1.md`, `feature-name-m2.md` - -Before writing a new spec, inspect related documents already in `specs/` so the structure matches the repository's style. - -Spec writing rules: - -- do not include concrete implementation plans -- focus on workflow, behavior, constraints, UX expectations, and acceptance -- describe what must be true, not how every class or method will be written -- preserve enough clarity that implementation can later be evaluated against the spec - -Recommended milestone spec sections: - -1. Overview -2. Goal -3. Scope -4. Non-goals -5. User experience or behavioral contract -6. Required workflow or lifecycle -7. Constraints and compatibility notes -8. Acceptance checklist -9. Open questions - -Recommended header style: - -- top title -- metadata table with fields such as `Version`, `Status`, `Date`, and optional `Parent Spec` - -Soft gate: - -- after the milestone spec set is written, pause for developer review before moving into implementation - -### Phase 5: One-milestone implementation planning - -Do not start coding a milestone until a milestone-specific implementation plan exists. - -For the current milestone only, write a concrete implementation plan that covers: - -- touched modules and files -- public contracts or interfaces that may change -- data flow or control flow implications -- testing or verification approach -- risk notes and fallback strategy if a design choice proves wrong - -This plan can be in the conversation unless the developer asks for a separate artifact. - -Soft gate: - -- before implementing each milestone, pause for confirmation if the implementation plan changes scope, introduces risk, or depends on a non-obvious trade-off - -### Phase 6: Implementation - -Implement only the current milestone. - -During implementation: - -- keep the work aligned with the current milestone spec -- avoid pulling future milestones into the same change unless explicitly requested -- surface spec mismatches as questions instead of silently redefining the milestone - -If a useful adjustment is discovered during implementation: - -1. explain the mismatch or new finding -2. compare it with the current milestone spec -3. ask whether the developer wants to update the scope, the spec, or the code plan - -### Phase 7: Spec-based validation - -After implementation, validate the result against the milestone spec. - -Use the milestone spec as the primary checklist. - -Review: - -- required behaviors -- workflow or lifecycle coverage -- UX expectations -- declared constraints -- acceptance checklist items - -If something is missing or different: - -- call it out explicitly -- ask whether the difference is intentional -- only then decide whether to patch the implementation or adjust the spec - -## What not to do - -- do not skip from vague feature request straight to code -- do not write milestone specs that are mostly implementation details -- do not implement multiple milestones just because the code paths are nearby -- do not treat external reference projects as copy sources -- do not quietly diverge from the agreed milestone spec - -## Response pattern - -When this skill is active, prefer this working rhythm: - -1. clarify the feature and decide whether external reference research is needed -2. research and summarize if approved -3. propose the milestone outline -4. discuss risks and feasibility -5. write milestone specs in `specs/` -6. choose one milestone -7. create the milestone implementation plan -8. implement -9. validate against the milestone spec - -## DotCraft-specific reminders - -- keep the repository's existing spec style in mind by reading related `specs/*.md` files before drafting a new one -- keep milestone specs high-level enough to survive implementation iteration -- use `references/` for cloned external repos when research is approved -- by default, summarize research in chat instead of creating additional documents diff --git a/plugins/dotcraft-dev/skills/feature-workflow/agents/openai.yaml b/plugins/dotcraft-dev/skills/feature-workflow/agents/openai.yaml deleted file mode 100644 index 6e99dd1..0000000 --- a/plugins/dotcraft-dev/skills/feature-workflow/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "DotCraft Feature Workflow" - short_description: "Guide large DotCraft feature development from planning through implementation" - default_prompt: "Use $dotcraft-feature-workflow to plan and deliver a substantial DotCraft feature." diff --git a/plugins/dotcraft-dev/skills/release-draft/SKILL.md b/plugins/dotcraft-dev/skills/release-draft/SKILL.md index 4bc267b..2401f20 100644 --- a/plugins/dotcraft-dev/skills/release-draft/SKILL.md +++ b/plugins/dotcraft-dev/skills/release-draft/SKILL.md @@ -5,7 +5,7 @@ description: Draft DotCraft GitHub Release notes from repository evidence. Use w # Release Draft -Use this skill to produce a GitHub Release body that feels consistent with recent DotCraft releases while staying grounded in current repo evidence. +Use this skill to produce an English GitHub Release body that feels consistent with recent DotCraft releases while staying grounded in current repo evidence. Evidence may be localized; synthesize the final release copy in English. ## Standard Workflow @@ -24,11 +24,11 @@ desktop/resources/whats-new/releases/.json Use each card's title, summary, and `media.url` as the core feature list and GIF source. -4. Read concise supporting docs for each feature before expanding copy. Prefer: +4. Read concise supporting docs for each feature before expanding copy. Discover the current documentation locales and prefer: -- `README.md` / `README_ZH.md` -- `docs/features/**` and `docs/zh/features/**` -- `docs/developing/sdk*.md` and `docs/zh/developing/sdk*.md` for App Binding / SDK items +- the current README and its localized mirrors +- feature documentation in every currently supported documentation locale +- relevant developer or SDK documentation across those locales - targeted `rg` results for feature names, PR titles, and config keys 5. Generate or reconstruct the GitHub "What's Changed" section. `releases/generate-notes` is allowed only as a non-publishing helper that returns text: @@ -71,13 +71,14 @@ DotCraft vX.Y.Z is a major release focused on ... ## Writing Rules -- Match the reference release's language, tone, heading style, and level of detail. If the reference is v0.1.6, use concise English GitHub Release copy with numbered feature sections. +- Write the complete release body in English. Keep identifiers, product names, code, and URLs in their canonical form. +- Match the reference release's tone, heading style, and level of detail. If the reference is v0.1.6, use concise copy with numbered feature sections. - Lead with user-visible capabilities from What's New. Put reliability, tooling, and polish in "Infrastructure and Experience Improvements." - Use the GIF URLs exactly from the What's New catalog when available. - Expand terse What's New summaries with repo/docs evidence, not speculation. -- Preserve product terminology: `Agent Teams`, `Mission`, `Team Leader`, `App Binding`, `ChatGPT subscription`, `What's New`. +- Preserve established product terminology. Examples (e.g., not an exhaustive list) include `Agent Teams`, `Mission`, `Team Leader`, `App Binding`, `ChatGPT subscription`, and `What's New`; inspect current product and documentation sources for additional terms. - Mention plan tiers only when supported by docs/code or existing release copy. -- Include generated "What's Changed" entries and the compare link verbatim unless cleaning obvious formatting only. +- Preserve generated "What's Changed" links and attribution. Translate any non-English entry titles faithfully so the release body remains English; do not add unsupported claims. - Never run commands that create, edit, publish, delete, or upload assets to a GitHub Release, such as `gh release create`, `gh release edit`, `gh release delete`, or `gh release upload`. - State that the user must perform the actual GitHub Release publishing step; you only provide the draft template. - If a tag or release does not exist yet, state that clearly and draft against the current branch/HEAD. @@ -90,4 +91,5 @@ Before returning the draft: - Confirm every highlighted feature has an evidence source. - Confirm each media link renders from `https://github.com/DotHarness/resources/raw/master/dotcraft/whats-new/`. - Confirm the compare range uses the previous release tag and target version. +- Confirm the release body is English except for canonical identifiers, product names, code, and URLs. - Keep the answer copy-paste ready. Add a short note after the draft only for sources, caveats, or missing data. diff --git a/plugins/dotcraft-dev/skills/release-draft/agents/openai.yaml b/plugins/dotcraft-dev/skills/release-draft/agents/openai.yaml index 0c5bbe2..cf8305c 100644 --- a/plugins/dotcraft-dev/skills/release-draft/agents/openai.yaml +++ b/plugins/dotcraft-dev/skills/release-draft/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Release Draft" short_description: "Draft DotCraft release notes from repo evidence" - default_prompt: "Use $release-draft to draft GitHub Release notes for a DotCraft version." + default_prompt: "Use $release-draft to draft English GitHub Release notes for a DotCraft version." diff --git a/plugins/dotcraft-dev/skills/ui-prototype/SKILL.md b/plugins/dotcraft-dev/skills/ui-prototype/SKILL.md deleted file mode 100644 index 239cdad..0000000 --- a/plugins/dotcraft-dev/skills/ui-prototype/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: ui-prototype -description: Create standalone interactive prototypes for DotCraft Desktop UI changes before touching production code, using static HTML for loose visual exploration and TSX previews for Desktop-coupled surfaces. Use when exploring DotCraft desktop layout, visual states, badges, controls, responsive widths, interaction flows, or design references that should live outside the source repository and be reviewed in the in-app browser before implementation. ---- - -# DotCraft UI Prototype - -Use this skill to separate visual/product design iteration from production Desktop changes. - -## Repository Setup - -Work with two repositories: - -- DotCraft source repository: the current `dotcraft` checkout. -- DotCraft design repository: by default, a sibling directory named `dotcraft-design` next to the source checkout. - -If the design repository does not exist, ask the user before creating it, or ask them to provide the prototype/design artifact directory. Do not hardcode absolute local paths in the skill, artifacts, or instructions. - -## Workflow - -1. Confirm the design question and scope. - - Identify the UI surface, states, constraints, and what must stay unchanged. - - Keep production wording, colors, or behavior stable unless the user explicitly wants to explore those dimensions. - -2. Choose the preview fidelity. - - Prefer a single `.html` file with embedded CSS and minimal JavaScript for early visual exploration, copy/layout alternatives, and designs that do not depend on Desktop runtime behavior. - - Use a TSX preview in the design repository when the result is tightly coupled to Desktop implementation details, such as real React components, renderer stores, tokens, icons, locale providers, truncation behavior, hover/focus state, or measured grid/flex layout. - - Keep existing HTML references as design notes and comparison material when useful, but do not treat them as the final pixel source for Desktop-coupled behavior once a TSX preview exists. - -3. Create or update a standalone artifact in the design repository. - - For HTML prototypes, prefer a single `.html` file with embedded CSS and minimal JavaScript. - - Group artifacts by product area when useful, such as `desktop/thread-list/...`. - - Do not depend on the DotCraft Desktop build, renderer stores, production components, or network assets for ordinary HTML prototypes. - - For TSX previews, use the design repository as a thin host that imports the real Desktop source from the sibling DotCraft checkout, rather than copying production components into the design repository. - -4. Model realistic states and edge cases. - - Include narrow and normal widths, long labels, empty/loading/error/pending states, selected and inactive rows, hover/focus where relevant, and controls for the variables under discussion. - - Use side-by-side comparison when evaluating current versus candidate layouts. - - Make controls interactive enough for review in the in-app browser. - -5. Review with the in-app browser. - - Open static HTML artifacts from the design repository with a local `file://` URL. - - Open TSX previews through the local Vite dev server for that preview entry. - - Iterate on the prototype artifact until the user confirms the visual direction. - - Treat screenshots, DOM measurements, and browser observations as design feedback. For TSX previews, also use them to reduce implementation drift before editing the DotCraft source repository. - -6. Handoff before production implementation. - - Summarize the approved layout decisions, interaction behavior, tokens, and unresolved risks. - - Only edit the DotCraft source repository after the user explicitly approves implementing the chosen design. - - Before production Desktop visual edits, read `specs/clients/DESIGN.md` from the DotCraft source repository and follow the repository's normal development/test workflow. - -## TSX Desktop Preview - -Use this path when a static HTML reference is likely to drift from Desktop behavior. Good triggers include: - -- the UI depends on an existing Desktop React component or renderer store -- the issue involves exact text measurement, truncation, grid/flex tracks, hover/focus actions, badges, icons, or status slots -- the visual defect appears only after production state changes, such as loading, running, confirmation, unread, pinned, or active-thread states -- prior HTML prototypes and Desktop implementation have already diverged - -Recommended setup: - -- Add a design-only React/Vite entry in the design repository under the relevant product area, for example `desktop/thread-list/tsx-preview/`. -- Configure the preview to import Desktop source from the sibling DotCraft checkout by default, with an environment variable such as `DOTCRAFT_ROOT` for override. -- Alias renderer imports to the Desktop renderer source and dedupe shared runtime dependencies such as `react`, `react-dom`, `zustand`, and icon libraries. -- Import the real Desktop component, tokens, icons, providers, stores, and locale setup needed by the surface. -- Mock only the minimum `window.api` surface required for the component to render and respond to review interactions. -- Seed realistic store state directly in the preview and expose small controls for width, state, and interaction mode. -- Keep the preview self-contained in the design repository. The DotCraft source repository should be read-only until the user approves the production change. - -Validation expectations: - -- Run the preview build script, such as `npm run build:`, before using the TSX preview as implementation evidence. -- Use the in-app browser to verify the page is non-empty, has no framework overlay, and has no relevant console errors. -- Measure the actual DOM geometry when the issue is spacing, alignment, or layout shift. Prefer concrete checks such as grid tracks, bounding boxes, and gaps over visual impressions alone. -- Capture screenshots of the reviewed states, especially default versus hover/focus/confirm states or narrow versus normal widths. -- After production implementation, compare Desktop and TSX preview behavior and add targeted tests only where they protect a real regression. - -## Artifact Standards - -- Keep prototypes clearly non-production: mock data, local state, and explanatory labels are allowed. -- Preserve user-visible strings from production only when they are part of the design question. -- Keep dimensions and constraints explicit, especially status slots, truncation, alignment, and responsive width behavior. -- Prefer CSS variables for candidate tokens so color, spacing, and sizing can be tuned quickly. -- Avoid decorative UI that is not relevant to the design decision. -- Include enough inline notes in the page for reviewers to understand what is being compared without reading production code. - -## Handoff Notes - -When the prototype is approved, report: - -- the design artifact path -- whether the reviewed source of truth was static HTML or TSX importing Desktop source -- the confirmed UI states and constraints -- the browser/build evidence used for review, including screenshots or DOM measurements when relevant -- the implementation surface in the DotCraft source repository -- any choices that still need product confirmation diff --git a/plugins/dotcraft-dev/skills/ui-prototype/agents/openai.yaml b/plugins/dotcraft-dev/skills/ui-prototype/agents/openai.yaml deleted file mode 100644 index 26c8816..0000000 --- a/plugins/dotcraft-dev/skills/ui-prototype/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "DotCraft UI Prototype" - short_description: "Prototype DotCraft UI before production edits" - default_prompt: "Use $ui-prototype to create or update a standalone interactive HTML prototype for a DotCraft Desktop UI change before editing production code." diff --git a/plugins/harness-workflow/.craft-plugin/plugin.json b/plugins/harness-workflow/.craft-plugin/plugin.json new file mode 100644 index 0000000..4871cfe --- /dev/null +++ b/plugins/harness-workflow/.craft-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "schemaVersion": 1, + "id": "harness-workflow", + "version": "0.1.0", + "displayName": "Harness Workflow", + "description": "Shared product-development workflows from DotHarness.", + "capabilities": ["skill"], + "skills": "./skills/", + "interface": { + "displayName": "Harness Workflow", + "shortDescription": "Shared feature planning, UI prototyping, and SVG workflows.", + "longDescription": "Reusable DotHarness workflows for substantial feature planning, isolated UI prototyping, and repo-native SVG asset design across products and technology stacks.", + "developerName": "DotHarness", + "category": "Engineering", + "capabilities": ["Skill"], + "defaultPrompt": "Help me plan and deliver this product change, including any UI prototype or SVG assets it needs.", + "brandColor": "#050505", + "composerIcon": "./assets/harness-workflow.svg", + "logo": "./assets/harness-workflow.svg" + } +} diff --git a/plugins/harness-workflow/assets/harness-workflow.svg b/plugins/harness-workflow/assets/harness-workflow.svg new file mode 100644 index 0000000..f31cbfd --- /dev/null +++ b/plugins/harness-workflow/assets/harness-workflow.svg @@ -0,0 +1,11 @@ + + Harness Workflow + The white DotHarness mark on a full-bleed black square with a blue three-node workflow path. + + + + + + + + diff --git a/plugins/harness-workflow/skills/feature-workflow/SKILL.md b/plugins/harness-workflow/skills/feature-workflow/SKILL.md new file mode 100644 index 0000000..96c6d42 --- /dev/null +++ b/plugins/harness-workflow/skills/feature-workflow/SKILL.md @@ -0,0 +1,190 @@ +--- +name: feature-workflow +description: Guides substantial feature development through repository research, a stable main specification, temporary milestone contracts, one-milestone-at-a-time implementation, user acceptance, and final spec consolidation. Use when planning or delivering a major feature, a multi-milestone capability, or any request that should be fully designed before implementation. +--- + +# Feature Workflow + +Use a research-first, spec-first process for large features. Establish the complete design before implementation, deliver it in accepted milestones, and keep milestone mechanics out of production artifacts. + +## Core rules + +1. Research the current project before designing the feature. +2. Define one main spec for the complete feature before implementation. +3. Treat the main spec as the durable contract. Update it before changing behavior, architecture, or workflow in code. +4. Define all milestone contracts up front, then implement one milestone at a time unless the user explicitly requests bundled delivery. +5. After each milestone, validate it and stop for user acceptance unless the user explicitly asks to continue without stopping. +6. Keep milestone files and terminology temporary. Do not expose them in the final repository or commit history. + +Do enough research and confirmation to keep the main spec stable. Do not rewrite it merely to make divergent implementation appear compliant; when the agreed contract still stands, correct the implementation instead. + +## Discover project conventions + +Inspect repository guidance and existing specifications before creating artifacts. + +- If the user designates an existing Markdown file, use it as the main spec. +- Otherwise, follow the project's established spec location, naming, and structure. Ask before creating the main spec only when the correct target cannot be determined. +- Store temporary milestone specs under the repository-root `references/` directory by default. A user-specified location overrides this default. +- Never stage or commit temporary milestone specs. + +## Phase 1: Research and scope + +Always inspect the current project. Read the relevant code, existing specs, tests, documentation, and repository history needed to understand: + +- the feature goal, users, success criteria, and non-goals +- current architecture, module boundaries, contracts, and lifecycle +- compatibility, migration, UX, and testing constraints +- existing behavior that must remain stable +- unresolved decisions that could change the design + +Discuss external research when prior art could materially improve the design. Search or clone external projects only when useful and approved. Summarize reusable ideas, rejected patterns, and remaining questions in the conversation unless the user requests a persistent research artifact. + +Resolve material uncertainty before treating the design as ready. + +Before authoring specs, review feasibility with the user when it exposes meaningful trade-offs. Cover architecture pressure, compatibility or migration concerns, UX complexity, testing difficulty, and whether the proposed milestone split is realistic. + +## Phase 2: Main spec and milestone contracts + +Draft the main spec first, derive the milestone outline and contracts from it, then present the complete set together for review. + +Follow the project's existing spec format when one exists. Otherwise, use the fallback structures below. + +### Main spec + +Make the main spec the durable source of truth for the finished feature. Capture the core design and workflow contract, including: + +- goals, scope, and non-goals +- architecture and system boundaries +- user and system workflows +- public behavior, contracts, and lifecycle +- constraints, compatibility, and failure behavior +- acceptance criteria for the completed feature + +Describe what must be true without turning the spec into a file-by-file implementation plan. + +When no project format exists, use: + +1. Overview +2. Goal +3. Scope +4. Non-goals +5. Core design and architecture +6. User and system workflows +7. Behavioral contracts and lifecycle +8. Constraints and compatibility +9. Acceptance checklist +10. Open questions + +Start with a title and a metadata table containing `Version`, `Status`, and `Date`. Include `Parent Spec` when this feature extends a broader specification. Resolve material open questions before implementation begins. + +### Milestone outline + +Produce a milestone outline before writing the detailed milestone specs. Each milestone needs a short name, user or product goal, expected outcome, out-of-scope boundary, and major dependencies or blockers. + +Use this fallback structure: + +```markdown +## Milestone Outline + +- M1: [name] + Goal: [...] + Expected outcome: [...] + Out of scope: [...] + Dependencies: [...] + +- M2: [name] + Goal: [...] + Expected outcome: [...] + Out of scope: [...] + Dependencies: [...] +``` + +Keep the outline at product and behavior level. It is a planning scaffold, not an implementation plan. + +### Milestone specs + +Create all temporary milestone specs under `references/` or the user-approved location. Each milestone spec should define: + +- its goal and incremental outcome +- included and excluded scope +- dependencies and ordering constraints +- behavior added or made observable in that milestone +- milestone-specific acceptance criteria + +Do not put concrete file edits, class designs, or step-by-step implementation instructions in milestone specs. Those belong to the per-milestone implementation plan. + +When no project naming convention exists, use numbered filenames such as `feature-name-m1.md` and `feature-name-m2.md`. Start each file with a title and a metadata table containing `Version`, `Status`, `Date`, and `Parent Spec`. + +Use this fallback section order: + +1. Overview +2. Goal +3. Scope +4. Non-goals +5. User experience or behavioral contract +6. Required workflow or lifecycle +7. Constraints and compatibility notes +8. Acceptance checklist +9. Open questions + +Split milestones so each produces a coherent, reviewable increment. Confirm that their combined outcomes satisfy the main spec. + +Do not begin implementation until the user has reviewed and confirmed the main spec and milestone set. + +## Phase 3: Plan and implement one milestone + +Before each milestone, create a concrete implementation plan for that milestone only. Cover: + +- affected modules and files +- contracts or interfaces that change +- data and control flow implications +- tests and verification +- risks and fallback choices + +Keep this plan in the conversation unless the user requests another artifact. + +Pause for confirmation before implementation when the plan changes scope, introduces material risk, or depends on a non-obvious trade-off. + +Implement only the active milestone. Do not pull later milestone work into it merely because code paths are nearby. + +If implementation reveals that behavior, architecture, workflow, or scope must change: + +1. update the main spec first +2. update affected unimplemented milestone specs +3. revise the active implementation plan +4. then change the implementation + +No separate approval is required merely because the main spec changes. Ask the user only when the underlying change exceeds the authorized scope, contradicts user intent, or requires a product decision. + +## Phase 4: Validate and accept the milestone + +Validate the implementation against both the active milestone spec and the main spec. Check required behavior, lifecycle, UX, constraints, compatibility, tests, and acceptance criteria. + +Report the evidence and stop for user acceptance by default. + +- If the result does not meet the existing contract, continue work on the current milestone. +- If feedback adds scope or changes the confirmed contract, update the main spec first and add or revise a later milestone. +- Do not mark the milestone complete until its acceptance criteria pass and the user accepts it. + +After acceptance, proceed to the next milestone and repeat the planning, implementation, validation, and acceptance cycle. + +## Phase 5: Consolidate the final spec + +After every milestone is implemented and accepted, check whether the user has already specified how to handle the temporary milestone specs. If not, ask whether to consolidate them into the main spec. + +When consolidation is approved: + +1. merge only durable final behavior, constraints, and decisions into the main spec +2. remove milestone ordering, progress history, and temporary development narration +3. verify that the main spec matches the accepted implementation +4. delete all temporary milestone spec files + +## Production hygiene + +Milestones are a development coordination mechanism, not a product concept. + +- Do not use milestone labels or phase narration in production code, tests, product documentation, or commit messages. +- Do not commit temporary milestone specs, even if they live inside the repository. +- Do not leave temporary milestone files behind after approved consolidation. +- Do not treat external reference projects as copy sources. +- Final artifacts should describe the feature and its behavior, not the sequence used to build it. diff --git a/plugins/harness-workflow/skills/feature-workflow/agents/openai.yaml b/plugins/harness-workflow/skills/feature-workflow/agents/openai.yaml new file mode 100644 index 0000000..f082da2 --- /dev/null +++ b/plugins/harness-workflow/skills/feature-workflow/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Feature Workflow" + short_description: "Research, specify, and deliver substantial features" + default_prompt: "Use $feature-workflow to research, specify, and deliver a substantial feature through accepted milestones." diff --git a/plugins/dotcraft-dev/skills/svg-design/SKILL.md b/plugins/harness-workflow/skills/svg-design/SKILL.md similarity index 100% rename from plugins/dotcraft-dev/skills/svg-design/SKILL.md rename to plugins/harness-workflow/skills/svg-design/SKILL.md diff --git a/plugins/dotcraft-dev/skills/svg-design/agents/openai.yaml b/plugins/harness-workflow/skills/svg-design/agents/openai.yaml similarity index 100% rename from plugins/dotcraft-dev/skills/svg-design/agents/openai.yaml rename to plugins/harness-workflow/skills/svg-design/agents/openai.yaml diff --git a/plugins/dotcraft-dev/skills/svg-design/references/svg_design_checklist.md b/plugins/harness-workflow/skills/svg-design/references/svg_design_checklist.md similarity index 100% rename from plugins/dotcraft-dev/skills/svg-design/references/svg_design_checklist.md rename to plugins/harness-workflow/skills/svg-design/references/svg_design_checklist.md diff --git a/plugins/dotcraft-dev/skills/svg-design/scripts/preview_svgs.mjs b/plugins/harness-workflow/skills/svg-design/scripts/preview_svgs.mjs similarity index 100% rename from plugins/dotcraft-dev/skills/svg-design/scripts/preview_svgs.mjs rename to plugins/harness-workflow/skills/svg-design/scripts/preview_svgs.mjs diff --git a/plugins/harness-workflow/skills/ui-prototype/SKILL.md b/plugins/harness-workflow/skills/ui-prototype/SKILL.md new file mode 100644 index 0000000..8444f30 --- /dev/null +++ b/plugins/harness-workflow/skills/ui-prototype/SKILL.md @@ -0,0 +1,99 @@ +--- +name: ui-prototype +description: Create standalone interactive UI prototypes before touching production code, using static HTML for loose visual exploration and the project's native UI framework for implementation-coupled previews. Use when exploring layouts, visual states, controls, responsive widths, interaction flows, or design references that should be reviewed outside the source repository before implementation. +--- + +# UI Prototype + +Use this skill to separate visual and product design iteration from production changes. + +## Repository setup + +Treat the current repository as the source repository. Derive the default design repository from its root directory name: a source repository named `` uses a sibling `-design` directory. + +- Prefer an existing sibling design repository when present. +- If it does not exist, ask before creating it or ask the user for another prototype artifact location. +- Do not hardcode absolute local paths in the skill, artifacts, or instructions. +- Keep the source repository read-only throughout prototype work. Edit it only after the user approves the design and asks for implementation. + +Before prototyping, discover the design guidance applicable to the target surface. Inspect repository instructions, design-system documentation, tokens, component conventions, and nearby implementation patterns. Use the guidance with the closest applicable scope. If multiple sources conflict and scope does not resolve the conflict, ask the user. + +## Workflow + +1. Confirm the design question and scope. + - Identify the UI surface, states, constraints, and what must stay unchanged. + - Keep production wording, colors, and behavior stable unless the user explicitly wants to explore them. + +2. Choose the preview fidelity. + - Prefer one standalone `.html` file with embedded CSS and minimal JavaScript for early visual exploration, copy or layout alternatives, and concepts that do not require production runtime behavior. + - When fidelity depends on real components, state, tokens, providers, text measurement, or framework layout behavior, use the project's native UI framework in the design repository. + - Use TSX only when the source project uses React and TSX is appropriate to the target surface. + - Keep earlier HTML references as design notes when useful, but do not treat them as the final pixel source after a framework-coupled preview exists. + +3. Create or update a standalone artifact in the design repository. + - Group artifacts by product area when useful. + - Keep ordinary HTML prototypes independent of the production build, production state, production components, and network assets. + - For a framework-coupled preview, use the design repository as a thin host that reuses the relevant source components and design primitives instead of copying them. + - Mock only the minimum application boundary needed for realistic review. + +4. Model realistic states and edge cases. + - Include narrow and normal widths, long labels, empty/loading/error/pending states, selected and inactive rows, hover/focus where relevant, and controls for the variables under discussion. + - Use side-by-side comparison when evaluating current and candidate layouts. + - Make controls interactive enough for browser review. + +5. Review in a browser. + - Open standalone HTML directly or serve it locally when browser restrictions require it. + - Run framework previews with the design repository's existing development or preview tooling. + - Iterate until the user confirms the visual direction. + - Treat screenshots, DOM measurements, and browser observations as design evidence. Use them to reduce implementation drift before editing production code. + +6. Handoff before production implementation. + - Summarize approved layout decisions, interaction behavior, tokens, and unresolved risks. + - Record the applicable project design guidance and the production surface that would change. + - Only enter implementation after explicit user approval, then follow the source repository's development and verification workflow. + +## Framework-coupled preview + +Use this path when a standalone HTML reference is likely to drift from production behavior. Good triggers include: + +- the UI depends on an existing production component, state container, provider, or design token +- the issue involves exact text measurement, truncation, grid or flex tracks, hover/focus actions, badges, icons, or status slots +- the visual defect appears only after application state changes +- a prior static prototype and production implementation have diverged + +Recommended setup: + +- Add a design-only entry under the relevant product area in the design repository. +- Reuse the source project's framework, package manager, and established preview/build conventions. +- Import the real components, tokens, icons, providers, and state needed by the surface when repository boundaries allow it. +- Mock only the minimum host API required for review interactions. +- Seed realistic state and expose small controls for width, state, and interaction mode. +- Keep all preview-specific code in the design repository. + +Validation expectations: + +- Run the artifact's build or validation command before using it as implementation evidence. +- Verify the page is non-empty and has no relevant runtime, framework, or console errors. +- Measure actual DOM geometry when reviewing spacing, alignment, truncation, or layout shift; prefer grid tracks, bounding boxes, and gaps over visual impressions alone. +- Capture screenshots of the reviewed states, especially interaction and width variants. +- After approved production implementation, compare the implementation with the reviewed prototype and add targeted tests only where they protect a real regression. + +## Artifact standards + +- Keep prototypes clearly non-production: mock data, local state, and explanatory labels are allowed. +- Preserve user-visible strings from production only when they are part of the design question. +- Keep dimensions and constraints explicit, especially status slots, truncation, alignment, and responsive behavior. +- Prefer editable design tokens or CSS variables so candidate values can be tuned quickly. +- Avoid decorative UI unrelated to the design decision. +- Include enough notes for reviewers to understand the comparison without reading production code. + +## Handoff notes + +When the prototype is approved, report: + +- the design artifact path +- whether the reviewed source of truth was standalone HTML or a project-native framework preview +- the confirmed UI states and constraints +- the browser/build evidence, including screenshots or DOM measurements when relevant +- the production implementation surface +- any choices that still need product confirmation diff --git a/plugins/harness-workflow/skills/ui-prototype/agents/openai.yaml b/plugins/harness-workflow/skills/ui-prototype/agents/openai.yaml new file mode 100644 index 0000000..9e6e317 --- /dev/null +++ b/plugins/harness-workflow/skills/ui-prototype/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "UI Prototype" + short_description: "Prototype UI safely before production implementation" + default_prompt: "Use $ui-prototype to create or update a standalone HTML or project-native UI prototype before editing production code." From 0b3b3389ce777a3f7b73e28be94e6c1b46b6654d Mon Sep 17 00:00:00 2001 From: AkiKurisu <2683987717@qq.com> Date: Wed, 15 Jul 2026 23:59:18 +0800 Subject: [PATCH 2/2] simplify description --- plugins/dotcraft-dev/skills/dev-guide/SKILL.md | 2 +- plugins/dotcraft-dev/skills/release-draft/SKILL.md | 2 +- plugins/harness-workflow/skills/feature-workflow/SKILL.md | 2 +- plugins/harness-workflow/skills/svg-design/SKILL.md | 2 +- plugins/harness-workflow/skills/ui-prototype/SKILL.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/dotcraft-dev/skills/dev-guide/SKILL.md b/plugins/dotcraft-dev/skills/dev-guide/SKILL.md index 6f6dded..eacf9ae 100644 --- a/plugins/dotcraft-dev/skills/dev-guide/SKILL.md +++ b/plugins/dotcraft-dev/skills/dev-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: dotcraft-dev-guide -description: Development workflow and project-specific norms for DotCraft. Use when changing protocol behavior or shipping user-facing features. Covers spec-first workflow, testing, localization, and documentation responsibilities. +description: DotCraft development conventions. Use when changing protocols or shipping user-facing functionality. --- # DotCraft Development Guide diff --git a/plugins/dotcraft-dev/skills/release-draft/SKILL.md b/plugins/dotcraft-dev/skills/release-draft/SKILL.md index 2401f20..65dda78 100644 --- a/plugins/dotcraft-dev/skills/release-draft/SKILL.md +++ b/plugins/dotcraft-dev/skills/release-draft/SKILL.md @@ -1,6 +1,6 @@ --- name: release-draft -description: Draft DotCraft GitHub Release notes from repository evidence. Use when asked to write, revise, or prepare release copy for a DotCraft version, especially from a prior release style, What's New cards, GIF asset links, generated GitHub notes, changelog ranges, README/docs feature descriptions, or release tag comparisons. +description: Draft DotCraft GitHub Release notes from repository evidence. Use when preparing or revising release copy for a version. --- # Release Draft diff --git a/plugins/harness-workflow/skills/feature-workflow/SKILL.md b/plugins/harness-workflow/skills/feature-workflow/SKILL.md index 96c6d42..798ac41 100644 --- a/plugins/harness-workflow/skills/feature-workflow/SKILL.md +++ b/plugins/harness-workflow/skills/feature-workflow/SKILL.md @@ -1,6 +1,6 @@ --- name: feature-workflow -description: Guides substantial feature development through repository research, a stable main specification, temporary milestone contracts, one-milestone-at-a-time implementation, user acceptance, and final spec consolidation. Use when planning or delivering a major feature, a multi-milestone capability, or any request that should be fully designed before implementation. +description: Plan and deliver substantial features through a stable spec and reviewed milestones. Use for large or multi-stage work that should be designed before implementation. --- # Feature Workflow diff --git a/plugins/harness-workflow/skills/svg-design/SKILL.md b/plugins/harness-workflow/skills/svg-design/SKILL.md index e8d4895..bd1460a 100644 --- a/plugins/harness-workflow/skills/svg-design/SKILL.md +++ b/plugins/harness-workflow/skills/svg-design/SKILL.md @@ -1,6 +1,6 @@ --- name: svg-design -description: Design, simplify, edit, preview, and validate SVG assets for product UI, desktop apps, documentation, skill icons, plugin icons, empty states, diagrams, or other repo-native vector graphics. Use when Codex needs to create a new SVG, refine an existing SVG, adapt a logo into a small icon, reduce visual clutter or overlap, preserve brand recognition at small sizes, or build a preview-and-screenshot workflow for SVG QA. +description: Create and refine SVG assets with visual validation. Use for product graphics, icons, diagrams, and other repository-native vectors. --- # SVG Asset Design diff --git a/plugins/harness-workflow/skills/ui-prototype/SKILL.md b/plugins/harness-workflow/skills/ui-prototype/SKILL.md index 8444f30..ef2a8b5 100644 --- a/plugins/harness-workflow/skills/ui-prototype/SKILL.md +++ b/plugins/harness-workflow/skills/ui-prototype/SKILL.md @@ -1,6 +1,6 @@ --- name: ui-prototype -description: Create standalone interactive UI prototypes before touching production code, using static HTML for loose visual exploration and the project's native UI framework for implementation-coupled previews. Use when exploring layouts, visual states, controls, responsive widths, interaction flows, or design references that should be reviewed outside the source repository before implementation. +description: Prototype UI outside production code for design review. Use when exploring layouts, states, responsive behavior, or interaction flows before implementation. --- # UI Prototype