@nt-ai-lab/opencode-skillz 0.3.10 → 0.3.12

package/commands/component-design.md

@@ -77,7 +77,7 @@ The following guidelines should be applied when designing components.
 
 ### Layering
 
-Components should be put into the correct layer based on the type of logic they contain.
+Components should be put into the correct layer based on the type of logic they contain. They MUST live in a folder (or sub folder) that represents their layer. Dumping everyting in the root of the module is forbidden (only entrypoints can live their like `index.ts` and `main.ts`)
 
 - `domain`: Business rules and domain logic. This should be kept pure and isolated from technical concerns like database transactions. A domain expert should be able to read it and understand it
 
@@ -85,7 +85,15 @@ Components should be put into the correct layer based on the type of logic they
 
 - `infra`: Technical capabilities live in here like database transactions, persistence, external service clients and so on. Use dedicated sub-folders to properly organize like `/persistence`, `/external-service`
 
-- `/infra/{gateway}`: This sub-layer handles receiving inputs from the outside world and returning responses to the outside world, like gateways sitting at the edge of the application. It's common to see http controllers and event handlers in this layer. Examples of `{gateway}` include `http`, `event-handlers`
+- `/infra/{gateway}`: This sub-layer handles receiving inputs from the outside world and returning responses to the outside world, like gateways sitting at the edge of the application. It's common to see http controllers and event handlers in this layer. Examples of `{gateway}` include `http`, `event-handlers`. Everything inside this layer must live in a sub-folder to avoid the root becoming a dumping ground and hiding design issues.
+
+The following folder names are baned because they are generic terms that become a dumping ground or workaround for bad design. Find a more precise name or ask for help.
+
+- `utils`
+- `helpers`
+- `models`
+- `core`
+- `shared`
 
 Each codebase has it's own layering conventions that should be respected, but when no layering convention exists use the above as the default.
 
@@ -203,4 +211,6 @@ Before presenting the final design, review every component name against all rule
 
 If any name violates any naming rule, revise the design before presenting it.
 
+Then review all components against all guidelines in Layering. If any components violates a layering rule, revise the design befor presenting it.
+
 Ask the user which option to approve, reject, or combine.

package/commands/create-pr.md

@@ -0,0 +1,155 @@
+---
+description: Create a draft pull request with semantic commits, source-of-truth references, and check monitoring
+---
+
+Create a draft pull request for the current branch.
+
+## Stop and ask the user if any of the following are true
+
+- The source of truth is missing or unclear
+- The ticket, plan, or design document cannot be found
+- The acceptance criteria cannot be copied from the source material
+- The branch contains unrelated changes that do not belong in the same pull request
+- The base branch is unclear
+- The change requires assumptions about user value, scope, or design intent
+- An existing commit title already on the branch does not comply with the required commit title format and fixing it would require rewriting history
+
+## Required context gathering
+
+Before creating commits or a pull request:
+
+1. Review the current git status
+2. Review staged and unstaged diffs
+3. Review the branch divergence from the base branch
+4. Review every commit that will be included in the pull request
+5. Review the source-of-truth materials for the change:
+   - ticket, such as JIRA
+   - plan
+   - design document
+   - any linked supporting document required to understand the change
+
+Do not create the pull request until the change scope and source documents are understood.
+
+## Local changes before pull request creation
+
+The pull request must not be created with uncommitted local changes.
+
+If local changes exist:
+
+1. Group them into coherent commits
+2. Create the required semantic commits
+3. Verify the working tree is clean
+
+Do not create the pull request until `git status` is clean.
+
+## Commit title rules
+
+Every commit included in the pull request must use the commit title format defined below.
+
+Use semantic commit types:
+
+- `feat`
+- `fix`
+- `refactor`
+- `perf`
+- `docs`
+- `test`
+- `build`
+- `ci`
+- `release`
+- `chore`
+
+Rules:
+
+- Never use `chore` when the change includes a version bump or release preparation
+- Use `release` for version bumps or release preparation work
+- Use the smallest accurate scope
+- The commit subject must describe the user-facing change or the real engineering outcome
+- Commit bodies are optional
+- Do not require existing commits to contain body sections
+
+Commit title format:
+
+`<type>(<scope>): <short summary>`
+
+## Pull request title
+
+Use a clear title that matches the real change. Reuse the best semantic commit subject when that is the best title.
+
+## Pull request description
+
+The pull request description must contain these sections in this order:
+
+- `## Problem`
+- `## Solution`
+- `## Acceptance Criteria`
+- `## Architecture and software design`
+
+### `## Problem`
+
+Include:
+
+- all relevant source-of-truth references
+- the actual user problem, business problem, or operational problem
+- the value of solving it
+
+### `## Solution`
+
+Include:
+
+- the selected solution
+- why this approach solves the problem
+- important constraints or tradeoffs that matter to reviewers
+
+### `## Acceptance Criteria`
+
+Rules:
+
+- copy the acceptance criteria from the source ticket or plan
+- do not invent new criteria without stating that they are additional reviewer notes
+- do not paraphrase loosely if exact wording exists in the source material
+
+Acceptance criteria describe verifiable outcomes like "Users can log i with their email address". An acceptance criteria is not an implementation instruction like "Add a script that accepts the same parameters". If you find yourself using workds like "add", "modify" in "acceptance criteria" stop and ask for help.
+
+### `## Architecture and software design`
+
+Describe major architectural changes like:
+
+1. Which packages / modules were added, removed, or impacted?
+2. Which components were added / modified inside each module and why?
+3. Are there any significant domain model changes (new concepts, changes to terminology)
+4. New or modified depeendecies between components
+5. New or modified dependencies on other services or libraries
+
+## Execution steps
+
+1. Confirm the branch is ready for a pull request
+2. If local changes exist, stage the relevant changes and create the required semantic commits until the working tree is clean
+3. Verify every commit included in the pull request complies with the required commit title format
+4. Push the branch if needed
+5. Create a draft pull request with the required description format
+6. Return the pull request URL
+7. Wait for pull request checks to complete
+8. Report the final status
+
+Create the pull request as a draft.
+
+## Check monitoring
+
+After creating the draft pull request:
+
+- wait for the pull request checks to finish
+- do not report success before the checks complete
+- if checks fail, report the failing checks and their status
+- if checks pass, report that the draft pull request is ready for review
+- do not merge unless the user explicitly asks for a merge
+
+## Output
+
+At the end, provide:
+
+- the commit messages used for commits created during this command
+- the pull request title
+- the pull request URL
+- the final check status
+- any blockers that still require user action

package/commands/review-pr.md

@@ -1,42 +1,82 @@
 ---
-description: Run Vitest coverage for a pull request and update the PR description coverage block
+description: Review PR code quality, test quality, and coverage
 ---
 
-Review pull request coverage for:
+Review pull request code quality, test quality, and coverage for:
 $ARGUMENTS
 
-## Software Design Compliance
+## PR Resolution
 
-Ensure all new and modified code complies with `/nt-skillz:software-design`
+1. Resolve the pull request from `$ARGUMENTS`.
+2. If `$ARGUMENTS` does not identify a PR URL or PR number, stop and ask for one.
+3. Run `gh pr diff <pr> --name-only` to identify changed files.
+4. Fetch existing PR review comments and do not post the same comment twice on the same line.
+
+## Parallel Review Subtasks
+
+The `Software Design Compliance` and `Test Quality` reviews should run in parallel.
+
+### Software Design Compliance
+
+Invoke the default subagent with a task prompt that requires it to:
+
+1. Review new and modified production code against `/nt-skillz:software-design`.
+2. Leave inline feedback only on changed PR diff lines.
+3. Prefix every inline message with `[Software Design]`.
+4. If a finding cannot be attached to a changed diff line, return it as a summary finding instead of posting an inline comment.
+5. Return the count of inline findings and summary findings.
+
+Provide the subagent with:
 
-Leave in-line feedback on the PR for lines that do not comply. Prefix messages with [Software Design]
+- the resolved PR identifier
+- the changed file list
+- the changed diff context
 
-## Test Quality 
 
-Ensure all new and modified tests comply with  `/nt-skillz-writing-tests`
+### Test Quality
 
-Leave in-line feedback on the PR for lines that do not comply. Prefix messages with [Test Quality]
+Invoke the default subagent with a task prompt that requires it to:
 
-## Test Coverage Analysis 
+1. Review new and modified tests against `/nt-skillz:writing-tests`.
+2. Leave inline feedback only on changed PR diff lines.
+3. Prefix every inline message with `[Test Quality]`.
+4. If a finding cannot be attached to a changed diff line, return it as a summary finding instead of posting an inline comment.
+5. Return the count of inline findings and summary findings.
+
+Provide the subagent with:
+
+- the resolved PR identifier
+- the changed file list
+- the changed diff context
+
+## Test Coverage Analysis
 
 Add a test coverage analysis results section to the PR description:
 
-1. Resolve the pull request from `$ARGUMENTS`.
-2. If `$ARGUMENTS` does not identify a PR URL or PR number, stop and ask for one.
-3. Run `gh pr diff <pr> --name-only`.
-4. For each changed path from that output, run `/nt-skillz:vitest-coverage <file>`.
-5. Ignore only runs that print a `SKIP:` line.
-6. If every run prints a `SKIP:` line, use one fenced `text` block containing `No changed TypeScript source files.` as the coverage content.
-7. Otherwise, build the PR coverage block in this exact shape:
+1. For each changed path from `gh pr diff <pr> --name-only`, run `/nt-skillz:vitest-coverage <file>`.
+2. Ignore only runs that print a `SKIP:` line.
+3. If every run prints a `SKIP:` line, use one fenced `text` block containing `No changed TypeScript source files.` as the coverage content.
+4. Otherwise, build the PR coverage block in this exact shape:
     - `<!-- nt-skillz-coverage:start -->`
     - `## Coverage`
     - one `### \`<file>\`` heading for each non-`SKIP:` file
     - one fenced `text` block containing the exact raw `/nt-skillz:vitest-coverage <file>` output directly under that file heading
     - `<!-- nt-skillz-coverage:end -->`
-8. Run `gh pr view <pr> --json body --jq '.body'` and use the returned text as the current PR body.
-9. If the current PR body already contains both marker lines, replace only the text from `<!-- nt-skillz-coverage:start -->` through `<!-- nt-skillz-coverage:end -->` with the new coverage block.
-10. If the current PR body does not contain both marker lines, append the new coverage block to the end of the PR body separated by two newlines.
-11. Write the updated PR body to a temporary file.
-12. Run `gh pr edit <pr> --body-file <temporary-file>`.
-13. Do not summarize, interpret, or paraphrase the coverage output.
-14. Do not modify any other part of the PR body.
+5. Run `gh pr view <pr> --json body --jq '.body'` and use the returned text as the current PR body.
+6. If the current PR body already contains both marker lines, replace only the text from `<!-- nt-skillz-coverage:start -->` through `<!-- nt-skillz-coverage:end -->` with the new coverage block.
+7. If the current PR body does not contain both marker lines, append the new coverage block to the end of the PR body separated by two newlines.
+8. Write the updated PR body to a temporary file.
+9. Run `gh pr edit <pr> --body-file <temporary-file>`.
+10. Do not summarize, interpret, or paraphrase the coverage output.
+11. Do not modify any other part of the PR body.
+
+## Final Report
+
+Report only:
+
+- software design inline findings count
+- software design summary findings count
+- test quality inline findings count
+- test quality summary findings count
+- coverage block update status
+- blockers that require user action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/opencode-skillz",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Bundled OpenCode commands and agents",
   "type": "module",
   "main": "dist/index.js",