From e487dd32e0b0d851b5c7e156dc83cb85bce182c5 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Thu, 23 Jul 2026 19:47:22 +0200 Subject: [PATCH 1/2] Add command stubs for 24 missing skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create .md routing files in .agents/commands/ for skills that were previously only accessible via the skill system. Each stub includes frontmatter (name, description, skill, category) and invokes the corresponding skill. Commands added: - Onboarding: adopt, onboard, skill-improve, skill-test - Design: art-bible, asset-audit, asset-spec, balance-check, consistency-check, content-audit, ux-design, ux-review - Architecture: propagate-design-change - QA: automated-smoke-test, perf-profile, playtest-report - Prototyping: hybrid-prototype - Release: changelog, estimate, gate-check, localize, patch-notes, scope-check - Ops: tech-debt Improves discoverability — users can now find these via /slash-command autocomplete in OpenCode. Closes #82 (task 1 of 2) --- .agents/commands/adopt.md | 8 ++++++++ .agents/commands/art-bible.md | 8 ++++++++ .agents/commands/asset-audit.md | 8 ++++++++ .agents/commands/asset-spec.md | 8 ++++++++ .agents/commands/automated-smoke-test.md | 8 ++++++++ .agents/commands/balance-check.md | 8 ++++++++ .agents/commands/changelog.md | 8 ++++++++ .agents/commands/consistency-check.md | 8 ++++++++ .agents/commands/content-audit.md | 8 ++++++++ .agents/commands/estimate.md | 8 ++++++++ .agents/commands/gate-check.md | 8 ++++++++ .agents/commands/hybrid-prototype.md | 8 ++++++++ .agents/commands/localize.md | 8 ++++++++ .agents/commands/onboard.md | 8 ++++++++ .agents/commands/patch-notes.md | 8 ++++++++ .agents/commands/perf-profile.md | 8 ++++++++ .agents/commands/playtest-report.md | 8 ++++++++ .agents/commands/propagate-design-change.md | 8 ++++++++ .agents/commands/scope-check.md | 8 ++++++++ .agents/commands/skill-improve.md | 8 ++++++++ .agents/commands/skill-test.md | 8 ++++++++ .agents/commands/tech-debt.md | 8 ++++++++ .agents/commands/ux-design.md | 8 ++++++++ .agents/commands/ux-review.md | 8 ++++++++ 24 files changed, 192 insertions(+) create mode 100644 .agents/commands/adopt.md create mode 100644 .agents/commands/art-bible.md create mode 100644 .agents/commands/asset-audit.md create mode 100644 .agents/commands/asset-spec.md create mode 100644 .agents/commands/automated-smoke-test.md create mode 100644 .agents/commands/balance-check.md create mode 100644 .agents/commands/changelog.md create mode 100644 .agents/commands/consistency-check.md create mode 100644 .agents/commands/content-audit.md create mode 100644 .agents/commands/estimate.md create mode 100644 .agents/commands/gate-check.md create mode 100644 .agents/commands/hybrid-prototype.md create mode 100644 .agents/commands/localize.md create mode 100644 .agents/commands/onboard.md create mode 100644 .agents/commands/patch-notes.md create mode 100644 .agents/commands/perf-profile.md create mode 100644 .agents/commands/playtest-report.md create mode 100644 .agents/commands/propagate-design-change.md create mode 100644 .agents/commands/scope-check.md create mode 100644 .agents/commands/skill-improve.md create mode 100644 .agents/commands/skill-test.md create mode 100644 .agents/commands/tech-debt.md create mode 100644 .agents/commands/ux-design.md create mode 100644 .agents/commands/ux-review.md diff --git a/.agents/commands/adopt.md b/.agents/commands/adopt.md new file mode 100644 index 0000000..ac25c2b --- /dev/null +++ b/.agents/commands/adopt.md @@ -0,0 +1,8 @@ +--- +name: adopt +description: "Brownfield onboarding audit and migration plan" +skill: adopt +category: onboarding +--- + +Invokes `/adopt` skill. diff --git a/.agents/commands/art-bible.md b/.agents/commands/art-bible.md new file mode 100644 index 0000000..549fdc0 --- /dev/null +++ b/.agents/commands/art-bible.md @@ -0,0 +1,8 @@ +--- +name: art-bible +description: "Guided visual identity specification authoring" +skill: art-bible +category: design +--- + +Invokes `/art-bible` skill. diff --git a/.agents/commands/asset-audit.md b/.agents/commands/asset-audit.md new file mode 100644 index 0000000..9ba0424 --- /dev/null +++ b/.agents/commands/asset-audit.md @@ -0,0 +1,8 @@ +--- +name: asset-audit +description: "Audit assets for compliance with standards" +skill: asset-audit +category: design +--- + +Invokes `/asset-audit` skill. diff --git a/.agents/commands/asset-spec.md b/.agents/commands/asset-spec.md new file mode 100644 index 0000000..91ba841 --- /dev/null +++ b/.agents/commands/asset-spec.md @@ -0,0 +1,8 @@ +--- +name: asset-spec +description: "Generate asset visual specifications and AI prompts" +skill: asset-spec +category: design +--- + +Invokes `/asset-spec` skill. diff --git a/.agents/commands/automated-smoke-test.md b/.agents/commands/automated-smoke-test.md new file mode 100644 index 0000000..65ae6d4 --- /dev/null +++ b/.agents/commands/automated-smoke-test.md @@ -0,0 +1,8 @@ +--- +name: automated-smoke-test +description: "Run automated smoke test using engine MCP" +skill: automated-smoke-test +category: qa +--- + +Invokes `/automated-smoke-test` skill. diff --git a/.agents/commands/balance-check.md b/.agents/commands/balance-check.md new file mode 100644 index 0000000..67f3624 --- /dev/null +++ b/.agents/commands/balance-check.md @@ -0,0 +1,8 @@ +--- +name: balance-check +description: "Analyze game balance data and configurations" +skill: balance-check +category: design +--- + +Invokes `/balance-check` skill. diff --git a/.agents/commands/changelog.md b/.agents/commands/changelog.md new file mode 100644 index 0000000..202fd0c --- /dev/null +++ b/.agents/commands/changelog.md @@ -0,0 +1,8 @@ +--- +name: changelog +description: "Auto-generate changelog from git and design docs" +skill: changelog +category: release +--- + +Invokes `/changelog` skill. diff --git a/.agents/commands/consistency-check.md b/.agents/commands/consistency-check.md new file mode 100644 index 0000000..864c78e --- /dev/null +++ b/.agents/commands/consistency-check.md @@ -0,0 +1,8 @@ +--- +name: consistency-check +description: "Detect cross-document inconsistencies" +skill: consistency-check +category: design +--- + +Invokes `/consistency-check` skill. diff --git a/.agents/commands/content-audit.md b/.agents/commands/content-audit.md new file mode 100644 index 0000000..3ca96ba --- /dev/null +++ b/.agents/commands/content-audit.md @@ -0,0 +1,8 @@ +--- +name: content-audit +description: "Audit GDD-specified content vs implementation" +skill: content-audit +category: design +--- + +Invokes `/content-audit` skill. diff --git a/.agents/commands/estimate.md b/.agents/commands/estimate.md new file mode 100644 index 0000000..8dc4521 --- /dev/null +++ b/.agents/commands/estimate.md @@ -0,0 +1,8 @@ +--- +name: estimate +description: "Estimate task effort with confidence levels" +skill: estimate +category: release +--- + +Invokes `/estimate` skill. diff --git a/.agents/commands/gate-check.md b/.agents/commands/gate-check.md new file mode 100644 index 0000000..348a587 --- /dev/null +++ b/.agents/commands/gate-check.md @@ -0,0 +1,8 @@ +--- +name: gate-check +description: "Validate readiness to advance between phases" +skill: gate-check +category: release +--- + +Invokes `/gate-check` skill. diff --git a/.agents/commands/hybrid-prototype.md b/.agents/commands/hybrid-prototype.md new file mode 100644 index 0000000..2a9cd54 --- /dev/null +++ b/.agents/commands/hybrid-prototype.md @@ -0,0 +1,8 @@ +--- +name: hybrid-prototype +description: "Fast-lane prototype for discovery phase" +skill: hybrid-prototype +category: prototyping +--- + +Invokes `/hybrid-prototype` skill. diff --git a/.agents/commands/localize.md b/.agents/commands/localize.md new file mode 100644 index 0000000..0c1d365 --- /dev/null +++ b/.agents/commands/localize.md @@ -0,0 +1,8 @@ +--- +name: localize +description: "Full localization pipeline and cultural review" +skill: localize +category: release +--- + +Invokes `/localize` skill. diff --git a/.agents/commands/onboard.md b/.agents/commands/onboard.md new file mode 100644 index 0000000..345aea5 --- /dev/null +++ b/.agents/commands/onboard.md @@ -0,0 +1,8 @@ +--- +name: onboard +description: "Generate contextual onboarding document" +skill: onboard +category: onboarding +--- + +Invokes `/onboard` skill. diff --git a/.agents/commands/patch-notes.md b/.agents/commands/patch-notes.md new file mode 100644 index 0000000..643f0e4 --- /dev/null +++ b/.agents/commands/patch-notes.md @@ -0,0 +1,8 @@ +--- +name: patch-notes +description: "Generate player-facing patch notes" +skill: patch-notes +category: release +--- + +Invokes `/patch-notes` skill. diff --git a/.agents/commands/perf-profile.md b/.agents/commands/perf-profile.md new file mode 100644 index 0000000..3ab9b0e --- /dev/null +++ b/.agents/commands/perf-profile.md @@ -0,0 +1,8 @@ +--- +name: perf-profile +description: "Structured performance profiling workflow" +skill: perf-profile +category: qa +--- + +Invokes `/perf-profile` skill. diff --git a/.agents/commands/playtest-report.md b/.agents/commands/playtest-report.md new file mode 100644 index 0000000..d98bc45 --- /dev/null +++ b/.agents/commands/playtest-report.md @@ -0,0 +1,8 @@ +--- +name: playtest-report +description: "Generate structured playtest report" +skill: playtest-report +category: qa +--- + +Invokes `/playtest-report` skill. diff --git a/.agents/commands/propagate-design-change.md b/.agents/commands/propagate-design-change.md new file mode 100644 index 0000000..823ddb1 --- /dev/null +++ b/.agents/commands/propagate-design-change.md @@ -0,0 +1,8 @@ +--- +name: propagate-design-change +description: "Propagate GDD changes to architecture and ADRs" +skill: propagate-design-change +category: architecture +--- + +Invokes `/propagate-design-change` skill. diff --git a/.agents/commands/scope-check.md b/.agents/commands/scope-check.md new file mode 100644 index 0000000..e3c3bda --- /dev/null +++ b/.agents/commands/scope-check.md @@ -0,0 +1,8 @@ +--- +name: scope-check +description: "Analyze feature or sprint for scope creep" +skill: scope-check +category: release +--- + +Invokes `/scope-check` skill. diff --git a/.agents/commands/skill-improve.md b/.agents/commands/skill-improve.md new file mode 100644 index 0000000..b2c67e4 --- /dev/null +++ b/.agents/commands/skill-improve.md @@ -0,0 +1,8 @@ +--- +name: skill-improve +description: "Improve skill using test-fix-retest loop" +skill: skill-improve +category: onboarding +--- + +Invokes `/skill-improve` skill. diff --git a/.agents/commands/skill-test.md b/.agents/commands/skill-test.md new file mode 100644 index 0000000..29c375f --- /dev/null +++ b/.agents/commands/skill-test.md @@ -0,0 +1,8 @@ +--- +name: skill-test +description: "Validate skill structural and behavioral compliance" +skill: skill-test +category: onboarding +--- + +Invokes `/skill-test` skill. diff --git a/.agents/commands/tech-debt.md b/.agents/commands/tech-debt.md new file mode 100644 index 0000000..9cd0f78 --- /dev/null +++ b/.agents/commands/tech-debt.md @@ -0,0 +1,8 @@ +--- +name: tech-debt +description: "Track and prioritize technical debt" +skill: tech-debt +category: ops +--- + +Invokes `/tech-debt` skill. diff --git a/.agents/commands/ux-design.md b/.agents/commands/ux-design.md new file mode 100644 index 0000000..84c7739 --- /dev/null +++ b/.agents/commands/ux-design.md @@ -0,0 +1,8 @@ +--- +name: ux-design +description: "Guided UX spec authoring for screens and flows" +skill: ux-design +category: design +--- + +Invokes `/ux-design` skill. diff --git a/.agents/commands/ux-review.md b/.agents/commands/ux-review.md new file mode 100644 index 0000000..eaccb6c --- /dev/null +++ b/.agents/commands/ux-review.md @@ -0,0 +1,8 @@ +--- +name: ux-review +description: "Validate UX spec for completeness and compliance" +skill: ux-review +category: design +--- + +Invokes `/ux-review` skill. From 05fd701f571761794e2ed8a53c993a7c9282655a Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Thu, 23 Jul 2026 19:47:37 +0200 Subject: [PATCH 2/2] Expand onboard skill with interactive decisions and error handling Increase onboard skill from 2.7KB to 10KB to match the quality bar of peer skills like /start and /explore. Changes: - Add 'question' to allowed-tools for interactive role selection - Add comprehensive error handling for missing files (AGENTS.md, agent definitions, directories) - Add edge case coverage (no argument, unrecognized roles, empty projects, git unavailable) - Add detailed scanning rules per role (programmers, designers, narrative, QA, production, artists) - Add structured document template with required sections - Add role-specific next steps and collaborative protocol The skill now gracefully handles missing data, asks for clarification when needed, and provides actionable guidance tailored to each role. Closes #82 (task 2 of 2) --- .agents/skills/onboard/SKILL.md | 148 +++++++++++++++++++++++++------- 1 file changed, 119 insertions(+), 29 deletions(-) diff --git a/.agents/skills/onboard/SKILL.md b/.agents/skills/onboard/SKILL.md index 5038e16..14023d8 100644 --- a/.agents/skills/onboard/SKILL.md +++ b/.agents/skills/onboard/SKILL.md @@ -3,87 +3,146 @@ name: onboard description: "Generates a contextual onboarding document for a new contributor or agent joining the project. Summarizes project state, architecture, conventions, and current priorities relevant to the specified role or area." argument-hint: "[role|area]" user-invocable: true -allowed-tools: Read, Glob, Grep, Write +allowed-tools: Read, Glob, Grep, Write, question model: opencode-go/deepseek-v4-flash --- -## Phase 1: Load Project Context +## Overview -Read AGENTS.md for project overview and standards. +This skill generates a contextual onboarding document tailored to a specific role or area. It loads project state, scans relevant directories, and produces a comprehensive guide for new contributors or agents. -Read the relevant agent definition from `.agents/agents/` if a specific role is specified. +**When to use `/onboard`:** +- A new team member (human or agent) is joining the project +- You need context on a specific area before starting work +- You want a quick reference for conventions, architecture, and current state + +**When NOT to use `/onboard`:** +- You need to audit an existing brownfield project's format compliance → use `/adopt` +- You need to detect project stage and missing artifacts → use `/project-stage-detect` +- You are the project owner reviewing overall status → use `/sprint-status` + +--- + +## Phase 1: Parse Arguments and Load Project Context + +Read the argument to determine the target role or area. If no argument is provided, use `question` to ask: + +- **Prompt**: "No role specified. Who is this onboarding document for?" +- **Options**: + - `Programmer` — Code architecture, patterns, conventions, current implementation state + - `Designer` — Design documents, GDDs, systems, balance data + - `Narrative` — Story docs, world-building, lore, character profiles + - `QA` — Test coverage, test plans, known bugs, QA conventions + - `Production` — Sprint plans, milestones, velocity, blockers + - `Artist` — Art bible, asset specs, asset audit results, visual standards + +If the user provides a role that doesn't match the options above, accept it and proceed. Map it to the closest category for scanning purposes. + +**Load project context:** + +1. Read `AGENTS.md` for project overview, technology stack, and standards. If the file does not exist or is empty, **stop and report**: "Cannot generate onboarding document: `AGENTS.md` is missing or unreadable. This file is required for project context." + +2. If a specific role is specified, read the corresponding agent definition from `.agents/agents/[role].md`. If the file does not exist, inform the user: "No agent definition found for `[role]`. Proceeding with generic onboarding." and continue without role-specific context. + +3. Read `docs/framework/technical-preferences.md` for engine and language configuration. If the file contains `[TO BE CONFIGURED]` for the engine, note that the engine is not yet configured in the onboarding document. --- ## Phase 2: Scan Relevant Area -- For programmers: scan `src/` for architecture, patterns, key files -- For designers: scan `design/` for existing design documents -- For narrative: scan `design/narrative/` for world-building and story docs -- For QA: scan `tests/` for existing test coverage -- For production: scan `production/` for current sprint and milestone +Based on the role or area, scan the appropriate directories. If a directory does not exist or is empty, note it in the onboarding document as "No [area] artifacts found yet." + +**Scanning rules:** + +- **Programmers**: Scan `src/` for source files (`*.gd`, `*.cs`, `*.cpp`, `*.h`, `*.rs`, `*.py`, `*.js`, `*.ts`). Identify architecture patterns (folder structure, naming conventions), key modules, and entry points. Check for `docs/architecture/` and read ADRs if present. + +- **Designers**: Scan `design/` for GDDs (`*.md` in `design/gdd/`), balance data, and system definitions. Count documents and note which systems have GDDs vs. which are missing. + +- **Narrative**: Scan `design/narrative/` for world-building docs, character profiles, story outlines. If the directory does not exist, check `design/` for any narrative-related files. + +- **QA**: Scan `tests/` for test files, test plans, and coverage reports. Check `production/qa/` for bug reports and triage data. Note test framework and patterns. -Read recent changes (git log if available) to understand current momentum. +- **Production**: Scan `production/` for sprint plans (`production/sprints/`), milestones (`production/milestones/`), session logs, and blockers. Read the most recent sprint plan if it exists. + +- **Artists**: Scan `assets/` for art files, check for art bible in `design/art-bible.md`, and look for asset specs in `design/asset-specs/`. Check `design/art/` if it exists. + +**Read recent changes** (if git is available): +- Run `git log --oneline -20` to understand current momentum +- Identify the most active areas and recent focus + +If git is not available or the repository has no commits, skip this step and note: "No git history available." --- ## Phase 3: Generate Onboarding Document +Assemble the onboarding document using this structure. Fill each section with information gathered from Phases 1 and 2. If information is missing, state "Not yet defined" or "No artifacts found" rather than leaving the section blank. + ```markdown # Onboarding: [Role/Area] ## Project Summary -[2-3 sentence summary of what this game is and its current state] +[2-3 sentence summary of what this game is and its current state. Pull from AGENTS.md and design/gdd/game-concept.md if it exists.] ## Your Role -[What this role does on this project, key responsibilities, who you report to] +[What this role does on this project, key responsibilities, who you report to. Pull from the agent definition if available.] ## Project Architecture -[Relevant architectural overview for this role] +[Relevant architectural overview for this role. For programmers: describe folder structure, key modules, dependencies. For designers: describe systems and their interactions. For others: describe how their work fits into the pipeline.] ### Key Directories | Directory | Contents | Your Interaction | |-----------|----------|-----------------| +| [dir] | [what's in it] | [how this role uses it] | ### Key Files | File | Purpose | Read Priority | |------|---------|--------------| +| [file] | [what it does] | [High/Medium/Low] | ## Current Standards and Conventions -[Summary of conventions relevant to this role from AGENTS.md and agent definition] +[Summary of conventions relevant to this role from AGENTS.md and agent definition. Include coding standards, naming conventions, documentation requirements, test requirements.] ## Current State of Your Area -[What has been built, what is in progress, what is planned next] +[What has been built, what is in progress, what is planned next. Pull from scan results and recent git commits.] ## Current Sprint Context -[What the team is working on now and what is expected of this role] +[What the team is working on now and what is expected of this role. Pull from production/sprints/ if available. If no sprint is active, state "No active sprint."] ## Key Dependencies -[What other roles/systems this role interacts with most] +[What other roles/systems this role interacts with most. For programmers: which systems they modify. For designers: which programmers implement their designs. For QA: which areas need testing.] ## Common Pitfalls -[Things that trip up new contributors in this area] +[Things that trip up new contributors in this area. Pull from AGENTS.md coordination rules, coding standards, and any TODO/FIXME comments in scanned files.] ## First Tasks [Suggested first tasks to get oriented and productive] -1. [Read these documents first] -2. [Review this code/content] -3. [Start with this small task] +1. **Read these documents first**: [list 3-5 key documents] +2. **Review this code/content**: [point to specific files or directories] +3. **Start with this small task**: [suggest a low-risk first task, e.g., "Fix a typo in a GDD" or "Add a unit test for an existing function"] ## Questions to Ask -[Questions the new contributor should ask to get fully oriented] +[Questions the new contributor should ask to get fully oriented. Examples: "What is the definition of done for a story?", "Who reviews my work?", "What is the deploy process?"] ``` --- -## Phase 4: Save Document +## Phase 4: Review and Save Document -Present the onboarding document to the user. +Present the onboarding document to the user in full. Do not truncate or summarize — show the complete document. -Ask: "May I write this to `production/onboarding/onboard-[role]-[date].md`?" +**Ask**: "May I write this to `production/onboarding/onboard-[role]-[date].md`?" -If yes, write the file, creating the directory if needed. +If yes: +1. Create the `production/onboarding/` directory if it does not exist +2. Write the file with the date in YYYY-MM-DD format +3. Confirm: "Onboarding document written to `[path]`." + +If no: +- Ask: "Would you like me to revise the document, or skip saving it?" +- If revise, ask what to change and regenerate the relevant sections +- If skip, proceed to Phase 5 without writing --- @@ -91,6 +150,37 @@ If yes, write the file, creating the directory if needed. Verdict: **COMPLETE** — onboarding document generated. -- Share the onboarding doc with the new contributor before their first session. -- Run `/sprint-status` to show the new contributor current progress. -- Run `/help` if the contributor needs guidance on what to work on next. +**Suggest next steps based on the role:** + +- **Programmers**: "Run `/sprint-status` to see current work, then `/dev-story [story-id]` to pick up a task." +- **Designers**: "Run `/design-system [system-name]` to author a new GDD, or `/design-review [gdd-path]` to review an existing one." +- **QA**: "Run `/qa-plan` to create a test plan, or `/smoke-check` to run the smoke test suite." +- **Production**: "Run `/sprint-plan` to create or update the current sprint, or `/milestone-review` to assess progress." +- **Artists**: "Run `/art-bible` to review or create the visual identity spec, or `/asset-spec [system]` to generate asset specifications." +- **Narrative**: "Run `/design-system narrative` to author narrative GDDs, or review existing docs in `design/narrative/`." + +**General**: "Run `/help` if you need guidance on what to work on next." + +--- + +## Edge Cases + +- **No argument provided**: Use `question` to ask for the role (see Phase 1). +- **AGENTS.md missing or unreadable**: Stop and report the error. Do not proceed without project context. +- **Role not found in `.agents/agents/`**: Proceed with generic onboarding, note the missing agent definition in the document. +- **Engine not configured**: Note in the document that the engine is not yet set up and recommend `/setup-engine`. +- **Empty project (no source files, no design docs, no production artifacts)**: Generate a minimal onboarding document noting that the project is in early setup phase. Recommend `/start` to begin the workflow. +- **Git not available or no commits**: Skip the git history section, note "No git history available." +- **User provides an unrecognized role**: Accept it, map to the closest category for scanning, and note in the document that no agent definition was found. +- **User declines to save the document**: Skip the write, proceed to next steps. Do not force the save. +- **Multiple roles specified** (e.g., "programmer and QA"): Generate separate onboarding documents for each role, or ask the user to pick one. + +--- + +## Collaborative Protocol + +1. **Ask first** — never assume the user wants to save the document without asking +2. **Show the full document** — do not truncate or summarize before asking to save +3. **Adapt to the role** — tailor the scan and document content to the specific role's needs +4. **Handle missing data gracefully** — note what's missing rather than leaving sections blank +5. **Suggest actionable next steps** — point to specific commands the user can run next