@nt-ai-lab/opencode-skillz 0.3.7 → 0.3.9

package/commands/component-design.md

@@ -0,0 +1,202 @@
+# Component Design Prompt
+
+Work with the user to design the software components for a new feature. Help the user to understand how the new code will look to avoid nasty surprises when reviewing the PR that require a lot of wasted time fixing problems with the design.
+
+Focus on presenting diverse options. The user will choose their preferred option. Don't hesitate to iterate and ask questions rather than making assumptions.
+
+Search all relevant existing code. If some of the code is in other repos, look there as well. Don't be lazy, more too much research is better than not enough. If you're unsure ask the user. As a general rule, if the supporting documenting or existing code references another repository, you should almost certainly be looking there. You can't design new code without understanding how it fits into the bigger picture.
+
+## Pre-flight checklist
+
+1. If the requirements are missing or unclear and you need to make assumptions, stop and discuss the options with the user.
+2. If is is not clear where the new code should be placed, or there are multiple viable options, stop and discuss the options with the user.
+3. If you have even 1% doubt on anything required to produce the design, stop and discuss the options with the user.
+
+## Task
+
+Generate 3 or more component design options.
+
+Options must be as unique as possible.
+
+Example criteria for identifying unique options:
+
+1. number of components => all of the code in 1 monolithic script vs breakign each fine-grained responsiblity into it's own component
+2. size of components
+3. touching existing code vs adding new code
+4. introducing dependencies
+5. coupling vs cohesion
+6. DDD vs non-DDD
+
+If two options have the same components with the same responsibilities, they are not unique.
+
+## Component Naming Guidelines
+
+All components must have names that comply with the following guidelines.
+
+### Intention Revealing
+
+A name must describe as clearly and precisely as possible what the the thing is and does.
+
+Good examples:
+- `aysnc-file-reader`
+- `date-selector`
+- `tax-calculator`
+
+Bad examples:
+- `data-manager`: what kind of data? how does it manage the data? The name tells us almost nothing here.
+- `orders-service`: it does something related to orders but we don't know what? Easy to dump multiple unrelated things into this (like domain logic and external service calls)
+
+### Domain-driven
+
+A name should use established domain terminology wherever possible and should not invent new words and phrases that do not exist in the domain
+
+### Compound noun phrases
+
+Use this pattern as the default: `[Domain Object][Business Action][Role Noun]`.
+
+Example: `InvoicePaymentCollector`
+
+- `Invoice` = domain object
+- `Payment` = business object/action target
+- `Collector` = role noun / responsibility noun
+
+### Forbidden terms
+
+The following should be avoided at all costs unless truly necessary and reflective of the business domain:
+
+- `util`
+- `helper`
+- `manager`
+- `service`
+
+If you are about to use one of these words, first look for a more precise alternative. "what kind of util?", "what kind of service?"...
+
+## Component Design Guidelines
+
+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.
+
+- `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
+
+- `use-case`: The use-case layer is like a menu, it describes the operations the application suppors like `place-order`, `cancel-order` and so on. Each use case is responsible for orchestrating domain logic and technical concerns. The most common pattern is start transaction => load domain object => invoke domain object => save domain object => return results
+
+- `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`
+
+Each codebase has it's own layering conventions that should be respected, but when no layering convention exists use the above as the default.
+
+### Component Archetypes
+
+The following are common component archetypes (non-exhaustive, do not be constrained by this list). If a comoponent matches the description of multiple of these, splitting into multiple component each aligned with a single archetype is an alternative option. However, when components are small are handle 1 thing well, it's ok to ecompass multiple archetypes.
+
+1. **entrypoint**: the part of the application that talks to the outside world, like a http controller. A thin layer that parses inputs and hands off to a `use-case` and formats the response
+2. **coordinator**: Responsible for orchesstrating multiplpe components  that starts a transaction, loads a database object and invokes an operation on it. A `use-case`: is a good example of a coordinator
+3. **stateless calculator**: takes an input, makes a decision, and returns an output.
+4. **mapper**: mapps from one format to another
+5. **aggregate**: manages the lifecycle of a domain concept protecting invariants. Will only operations to be performed if they permitted in the current state.
+6. **value-object**: an abstraction on top a certain piece of data like a `date`. Provides an API with domain terminology for operating on the underlying value. The underlying value cannot be accessed directly.
+7. **external service client**: provides methods that represent operations that can be called on a 3rd party service over the network
+8. **validator**: accepts as input some data and indicates a result indicating whether the data is valid according to specify rules, like an email validator
+9. **factory**: responsible for the construction of an object.
+10. **repository**: persists and loads objects, typically to and from a database. In domain-driven design a repository is responsible for saving and loading entire aggregates only and should never be used for partial or ad-hoc loading.
+11. **query service**: used to fetch information about an application, typically by querying a database. In domain-driven design, query services are used for read operations and repositories are used for write operations (although repositories can be used for read operations as well)
+
+### General guidelines
+
+1. **Maximum file size is 400 lines**, enforced by lint rules. A component must be decomposed into multiple smaller components when it reaches this limit
+
+## Output Format
+
+# Design Options: [Feature Name]
+
+## Option 1: [Name]
+
+Describe this option by outlining the philosophy behind it and it's key characteristics.
+
+### Diagram
+
+Rules:
+- Mark every node `[existing]`, `[new]`, or `[changed]`.
+- Show actual dependencies and calls, not a fake straight-line sequence.
+- A line means the source component directly calls or depends on the target component.
+- Do not connect two components if they do not directly call each other.
+- Use branches when one component calls multiple dependencies.
+- Label every line with the request, method call, response, event, or query.
+- Keep it small.
+
+```text
+Client
+  |
+  | request / methodCall()
+  v
+[changed] ExistingEntryPoint
+  |
+  | methodCall()
+  v
+[new] NewComponent
+  |\
+  | \ callDependencyA()
+  |  v
+  | [existing] ExistingDependencyA
+  |
+  | callDependencyB()
+  v
+[new] NewDependencyB
+```
+
+### Components
+
+| Component | Status | Role Archetypes | Responsibilities | Estimated Size |
+|---|---|---|---|---|
+| `ComponentName` | New / Existing / Changed | `entrypoint`, `coordinator`, `custom:bulk-copy-script` | <ul><li>Responsibility one</li><li>Responsibility two</li></ul> | Small / Medium / Large, or estimated lines |
+
+**note:**comopnent names must adhere to the component naming guidelines defined in this document
+
+**note:** role archetypes must use names from the Component Archetypes section when applicable. If a component does not match one of the listed archetypes, use a custom archetype prefixed with `custom:`. Example: `custom:bulk-copy-script`.
+
+### New Dependencies
+
+| Dependency | Status | Used By | Purpose |
+|---|---|---|---|
+| `DependencyName` | New / Existing / Changed | `ComponentName` | One sentence |
+
+### Code Shape
+
+List the main new or changed files only.
+
+```text
+src/
+  api/
+    ExistingEntryPoint.ts        [changed]
+  feature/
+    NewComponent.ts              [new]
+```
+
+### Why This Option Is Unique
+
+Explain the uniqueness using only these criteria:
+
+- number of components
+- size of components
+- touching existing code vs adding new code
+- introducing dependencies
+
+## Option 2: [Name]
+
+Use the same format as Option 1.
+
+## Option 3: [Name]
+
+Use the same format as Option 1.
+
+## Recommendation
+
+Recommend one option in 1 short paragraph.
+
+## Approval
+
+Ask the user which option to approve, reject, or combine.

package/commands/implement.md

@@ -16,3 +16,12 @@ After each small TypeScript code change, call `nt_skillz_lint` with only the `fi
 - all lint errors on new code must be addressed before continuing
 - if the lint fails on existing code, ignore the error unless it is very close to the new code
 - line-length limits do not count as existing code; if new code causes a file-length lint error, it must be fixed
+
+## Test Coverage
+
+Before each commit:
+
+1. Run `git diff --name-only --cached --diff-filter=ACMR -- '*.ts' '*.tsx'`.
+2. For each returned path, run `/nt-skillz:vitest-coverage <file>`.
+3. Ignore only runs that print a `SKIP:` line.
+4. Do not create the commit unless every remaining file has 100% Vitest coverage (or it's impossible to achieve 100% test coverage for the relevant component)

package/commands/plan.md

@@ -0,0 +1,82 @@
+---
+description: Create an implementation plan.
+---
+
+Plan:
+$ARGUMENTS
+
+Create a detailed implementation plan broken down into slices of functionality and not layer. Good Example: "Fuzzy searching on first name" is a slice of value. Bad Example: "Add data types" is just a layer of code that needs to be assembled later.
+
+Search all relevant existing code. If some of the code is in other repos, look there as well. Don't be lazy, more too much research is better than not enough. If you're unsure ask the user. As a general rule, if the supporting documenting or existing code references another repository, you should almost certainly be looking there.
+
+For each slide of value, challenge if it's needed. Find supporting evidence.
+
+## Context
+
+The plan starts with a context section explaining the problem that is being solved along with any relevant information like constraints. It also references any existing materials like notion pages. Context should be rich so that an engineer has all the information they need.
+
+## Slices
+
+List each slice of value that needs to be delivered and justify why it is necessary in a table with the column headings `slice`, `description`, `justification`.
+
+## Task checklist
+
+A plan is broken down into tasks. One task for each slice of value like "Fuzzy searching on first name" and each task is broken down into subtask. The task itself and each subtask are checklist items. This is crucial so that progress can be recorded by the engineer.
+
+Tasks should be detailed so that an engineer has all the information they need to implement the task.
+
+## Linting
+
+Include a lint check before each commit:
+- get the staged changed `.ts` and `.tsx` files
+- run `nt_skillz_lint` on the changed files
+- do not create the commit unless the lint check passes
+
+## Test Coverage
+
+Include a 100% Vitest coverage check before each commit:
+- get the staged changed `.ts` and `.tsx` files
+- ignore tests, declaration files, config files, and fixtures
+- run `/nt-skillz:vitest-coverage <file>` for each remaining file
+- do not create the commit unless every remaining file passes with 100% Vitest coverage
+
+## Software design & architecture
+
+Leave a placeholder `<software design and architecture>`.  This will be filled in by a following command.
+
+### Template
+
+```md
+## Context
+
+- Problem:
+- Constraints:
+- Related materials:
+
+## Software design & architecture
+
+
+
+## Tasks
+
+- [ ] Task 1: <slice of functionality>
+  - [ ] Subtask 1.1
+  - [ ] Subtask 1.2
+  - [ ] Run `nt_skillz_lint` on changed `.ts` and `.tsx` files
+  - [ ] Verify 100% test coverage using  `/nt-skillz:vitest-coverage <file>`
+  - [ ] Commit the changes
+- [ ] Task 2: <slice of functionality>
+  - [ ] Subtask 2.1
+  - [ ] Subtask 2.2
+  - [ ] Run `nt_skillz_lint` on changed `.ts` and `.tsx` files
+  - [ ] Verify 100% test coverage using  `/nt-skillz:vitest-coverage <file>`
+  - [ ] Commit the changes
+```
+
+## Important Notes
+
+- Stop if you cannot implement the plan as described. If the proposed design or functionality will not work in practice, discuss with the user
+
+- Ensure you mark of each subtask when complete
+
+- If parts of the plan are incomplete, missing, or placeholders refuse to implement and tell the user. Do not implement a flawed plan

package/commands/review-pr.md

@@ -0,0 +1,42 @@
+---
+description: Run Vitest coverage for a pull request and update the PR description coverage block
+---
+
+Review pull request coverage for:
+$ARGUMENTS
+
+## Software Design Compliance
+
+Ensure all new and modified code complies with `/nt-skillz:software-design`
+
+Leave in-line feedback on the PR for lines that do not comply. Prefix messages with [Software Design]
+
+## Test Quality 
+
+Ensure all new and modified tests comply with  `/nt-skillz-writing-tests`
+
+Leave in-line feedback on the PR for lines that do not comply. Prefix messages with [Test Quality]
+
+## 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:
+    - `<!-- 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.

package/commands/vitest-coverage.md

@@ -0,0 +1,35 @@
+---
+description: Reusable Vitest coverage workflow for TypeScript source files
+---
+
+Run Vitest coverage for:
+$ARGUMENTS
+
+Treat `$ARGUMENTS` as exactly one repository-relative file path and run this exact workflow.
+
+1. If the path does not end with `.ts` or `.tsx`, print exactly `SKIP: not a TypeScript source file` and stop.
+2. If the path matches any of these patterns, print exactly `SKIP: excluded TypeScript file` and stop:
+   - `*.spec.ts`
+   - `*.spec.tsx`
+   - `*.test.ts`
+   - `*.test.tsx`
+   - `*.d.ts`
+   - `*.config.ts`
+   - `*.config.tsx`
+   - any path containing `/fixtures/`
+   - any path containing `/__fixtures__/`
+3. Walk upward from the file directory and stop at the nearest directory containing `package.json`. Use that directory as the package root.
+4. If the file has no ancestor `package.json`, stop and report a blocker.
+5. Convert the file path to a path relative to the package root.
+6. From the package root, run exactly this command:
+   `vitest related <file> --run --coverage.enabled --coverage.include=<file> --coverage.reporter=text`
+7. Capture the raw Vitest `text` coverage output for that file.
+8. This coverage check fails unless the raw output contains a coverage row for `<file>`.
+9. This coverage check fails unless the coverage row for `<file>` shows all of the following:
+   - `100` in `% Stmts`
+   - `100` in `% Branch`
+   - `100` in `% Funcs`
+   - `100` in `% Lines`
+10. This coverage check fails if the coverage row for `<file>` has any uncovered line numbers.
+11. If the coverage check fails, print the raw failing Vitest `text` coverage output without summarizing it.
+12. If the coverage check passes, print the raw Vitest `text` coverage output without summarizing it.

package/dist/tools/lint.js

@@ -26,6 +26,7 @@ class LintExecutionError extends Error {
         super(message);
     }
 }
+const ansiEscapeSequencePattern = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, "g");
 const toolDirectory = path.dirname(fileURLToPath(import.meta.url));
 const toolRepositoryRoot = path.resolve(toolDirectory, "..", "..");
 const eslintConfigPath = path.join(toolRepositoryRoot, "scripts", "living-architecture-eslint.config.mjs");
@@ -130,6 +131,9 @@ function createLintTitle(filePaths, baseReference) {
     }
     return "Lint current TypeScript files";
 }
+function removeAnsiEscapeSequences(value) {
+    return value.replaceAll(ansiEscapeSequencePattern, "");
+}
 async function runEslint(repositoryRoot, lintTargets) {
     const previousLintRepositoryRoot = process.env.NT_SKILLZ_LINT_REPO_ROOT;
     process.env.NT_SKILLZ_LINT_REPO_ROOT = repositoryRoot;
@@ -142,7 +146,7 @@ async function runEslint(repositoryRoot, lintTargets) {
     try {
         const lintResults = await eslint.lintFiles(lintTargets);
         const formatter = await eslint.loadFormatter("stylish");
-        const formattedOutput = (await formatter.format(lintResults)).trim();
+        const formattedOutput = removeAnsiEscapeSequences((await formatter.format(lintResults)).trim());
         const errorCount = lintResults.reduce((count, lintResult) => count + lintResult.errorCount + lintResult.fatalErrorCount, 0);
         return {
             exitCode: errorCount > 0 ? 1 : 0,

package/package.json

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

package/scripts/living-architecture-eslint.config.mjs

@@ -22,8 +22,6 @@ if (!lintRepositoryRoot) {
 
 const typescriptFiles = ['**/*.ts', '**/*.tsx']
 const testFiles = ['**/*.spec.ts', '**/*.spec.tsx', '**/*.test.ts', '**/*.test.tsx']
-const thinLayerFiles = ['**/entrypoint/**/*.ts', '**/commands/**/*.ts', '**/queries/**/*.ts']
-const thinLayerIgnoredFiles = ['**/*.spec.ts', '**/*.test.ts']
 const ignoredPaths = [
   '**/dist',
   '**/out-tsc',
@@ -58,21 +56,6 @@ const noEmptyStringFallbackRule = {
 
 const restrictedSyntaxRules = ['error', noLetRule, noGenericErrorRule, noEmptyStringFallbackRule]
 
-const entrypointRestrictedSyntaxRules = [
-  'error',
-  noLetRule,
-  noGenericErrorRule,
-  {
-    selector: 'FunctionDeclaration:not([parent.type="ExportNamedDeclaration"])',
-    message: 'Entrypoints must not define private functions. Move logic to commands/, queries/, or infra/.',
-  },
-  {
-    selector: 'VariableDeclarator > ArrowFunctionExpression',
-    message: 'Entrypoints must not define private arrow functions. Move logic to commands/, queries/, or infra/.',
-  },
-  noEmptyStringFallbackRule,
-]
-
 const restrictedImportPatterns = [
   {
     group: ['*/utils/*', '*/utils', '*/utilities'],
@@ -229,20 +212,6 @@ export default tseslint.config(
       '@stylistic/object-property-newline': ['error', { allowAllPropertiesOnSameLine: false }],
     },
   },
-  {
-    files: thinLayerFiles,
-    ignores: thinLayerIgnoredFiles,
-    rules: {
-      'max-lines': ['error', { max: 150, skipBlankLines: true, skipComments: true }],
-    },
-  },
-  {
-    files: ['**/entrypoint/**/*.ts'],
-    ignores: thinLayerIgnoredFiles,
-    rules: {
-      'no-restricted-syntax': entrypointRestrictedSyntaxRules,
-    },
-  },
   {
     files: typescriptFiles,
     plugins: {