@igorlau/dotagents 1.0.10 → 1.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -88,12 +88,14 @@ The following skills load when a task needs them:
88
88
  | Skill | Purpose |
89
89
  | ----- | ------- |
90
90
  | `dot-plan` | Plan a change as small, verifiable steps. |
91
+ | `dot-implement` | Implement a change or roadmap task to the repository's and language's standards. |
91
92
  | `dot-code-review` | Review a diff for correctness bugs. |
92
93
  | `dot-commit` | Commit changes as small, logical commits. |
93
94
  | `dot-docs-writing` | Write docs in the Google developer documentation style. |
94
95
  | `dot-debug` | Diagnose hard bugs with a feedback loop. |
95
96
  | `dot-grill-me` | Start an interview that sharpens a plan. |
96
97
  | `dot-grilling` | Run the interview method behind `dot-grill-me`. |
98
+ | `dot-roadmap` | Split a grilled plan into phases and self-contained tasks. |
97
99
  | `dot-handoff` | Summarize a conversation for another agent. |
98
100
  | `dot-writing-for-agents` | Write skills, `AGENTS.md`, and `CLAUDE.md` files. |
99
101
 
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: dot-implement
3
+ description: Implement a feature, fix, refactor, or roadmap task to the repository's and the language's standards. Use when the user asks to build or change code, or to work a task from a dot-roadmap roadmap.
4
+ ---
5
+
6
+ # Implement
7
+
8
+ Turn a request, an approved plan, or a roadmap task into a working change that ends **green**: every check the work names passes, and you've shown the output.
9
+
10
+ ## Repository conventions first
11
+
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Write code that fits those conventions.
13
+
14
+ ## 1. Pin the work
15
+
16
+ Identify the source of the work:
17
+
18
+ - **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's decisions in full. The task's "Out of scope" is a hard boundary.
19
+ - **Approved plan**: the plan in this conversation, from `dot-plan` or the user.
20
+ - **Request**: anything else.
21
+
22
+ Done when you can state the goal, the scope boundary, and the check that proves the work is done.
23
+
24
+ ## 2. Plan when needed
25
+
26
+ A roadmap task or an approved plan is already the plan. For a request that touches more than one file, use the `dot-plan` skill and wait for the user's approval before you change any file. A single-file change goes straight to step 3.
27
+
28
+ ## 3. Build
29
+
30
+ For each language the change touches, read its reference if one exists:
31
+
32
+ - [`references/typescript.md`](references/typescript.md): TypeScript and TSX.
33
+
34
+ Work through the plan one step at a time, and run each step's check before you start the next one.
35
+
36
+ Done when every requirement of the task, plan, or request has code that meets it.
37
+
38
+ ## 4. Verify
39
+
40
+ Run the task's "Verify" section, the plan's final check, or the repository's tests, type checker, and linter, and show the output. Check every acceptance criterion one by one.
41
+
42
+ When verification fails, or the task or plan turns out wrong (a fact contradicts it, or meeting it needs work outside its scope), stop. Report the failing check or the conflicting fact and propose a change to the task or plan. Keep the task file, the roadmap's decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
43
+
44
+ For a roadmap task, tick its checkbox in the roadmap's `README.md` once everything passes.
45
+
46
+ Done when the work is green.
47
+
48
+ ## 5. Hand off
49
+
50
+ End with the verification output and anything you skipped or couldn't check. Suggest the `dot-code-review` skill for the diff, then the `dot-commit` skill. Leave the commit to the user.
@@ -0,0 +1,83 @@
1
+ # TypeScript reference
2
+
3
+ TypeScript rules for the [`dot-implement`](../SKILL.md) skill, based on the Google TypeScript style guide. They cover correctness, type safety, and API shape; leave formatting to the repository's formatter.
4
+
5
+ The repository's conventions and its compiler and linter configuration come first, then the always-on rules, then this reference. In a file that already breaks a rule, match the file for small changes instead of rewriting it, and keep style fixes out of a behavior change.
6
+
7
+ ## Types
8
+
9
+ - Use `unknown` for values of unknown type, and narrow it with `typeof`, `instanceof`, `in`, or a type guard before use. Reach for `any` only where no type can express the value, such as a test mock, with a comment that says why.
10
+ - Validate data that crosses a trust boundary at the boundary: `JSON.parse` output, request bodies, environment variables, and file contents. Parse it into a typed value once, instead of casting.
11
+ - Prefer a runtime check to a type assertion (`as`) or a non-null assertion (`!`): both silence the compiler without checking anything. When an assertion is safe for a reason the code doesn't show, add a comment with the reason.
12
+ - Write assertions with `as`, never `<T>value`. When a double assertion is unavoidable, go through `unknown`.
13
+ - Annotate object literals with their type (`const foo: Foo = {...}`) or check them with `satisfies`, instead of asserting them with `as Foo`. An annotation catches misspelled and stale fields where the literal is declared.
14
+ - Fix compiler errors at their cause. Leave out `@ts-ignore`, `@ts-expect-error`, and `@ts-nocheck`; in a test that must pass an unchecked value, cast that one expression and comment why.
15
+ - Leave out annotations the compiler infers trivially, such as `const x = 5`. Annotate when inference would produce `unknown` or a wider type than intended, or when a complex return type is hard to read.
16
+ - Use interfaces for object types, and type aliases for unions, tuples, functions, and other non-object types.
17
+ - Declare a structural implementation's type where you create it (`const horse: Animal = {...}`), so a mismatch fails there instead of at a distant call site.
18
+ - Keep `| null` and `| undefined` out of type aliases. Add them where a value can actually be absent, and handle absence close to where it arises.
19
+ - Use optional fields and parameters (`name?: string`) instead of `name: string | undefined`.
20
+ - Use the lowercase primitive types: `string`, `number`, `boolean`, `object`. Use `unknown`, `object`, or `Record<string, T>` instead of `{}`.
21
+ - Write `T[]` and `readonly T[]` for simple element types, and `Array<T>` for complex ones.
22
+ - Use `Map` and `Set` for dictionaries with keys known only at runtime, and `Record<K, V>` for a fixed set of keys.
23
+ - Choose the simplest type that expresses the code. A few repeated properties or an interface that extends another beat a mapped or conditional type that readers must evaluate in their heads.
24
+ - Avoid generics that appear only in the return type. When an existing API has one, specify the type argument explicitly.
25
+ - Treat an indexed read from an array or a record as possibly `undefined`, and check it before use, even when `noUncheckedIndexedAccess` is off.
26
+
27
+ ## Modules
28
+
29
+ - Use ES module syntax: `import` and `export`. Leave out `namespace`, `/// <reference>`, and `import x = require(...)`; use separate files to group code.
30
+ - Use named exports. Use a default import only for external code that requires it.
31
+ - Export only what other modules use. Use plain module-level functions and constants instead of classes that hold only static members.
32
+ - Keep exports immutable: never `export let`. Expose a mutable value through a getter function.
33
+ - Use `import type` for symbols used only as types, and `export type` to re-export types.
34
+ - Import project files with relative paths.
35
+
36
+ ## Variables and data
37
+
38
+ - Declare with `const` by default and `let` when you reassign. Never use `var`. Declare one variable per statement, before its first use.
39
+ - Create arrays and objects with literals, not the `Array` or `Object` constructors.
40
+ - Spread only matching values: iterables into arrays, plain objects into objects. Never spread `null`, `undefined`, or primitives.
41
+ - Iterate arrays with `for...of`. Iterate objects with `Object.keys`, `Object.values`, or `Object.entries`; a `for...in` loop also visits inherited properties.
42
+ - Keep parameter destructuring to one level of shorthand properties, with defaults on the left side.
43
+ - Parse numbers with `Number()` and check the result for `NaN`. Use `parseInt` only for a radix other than 10, after checking the digits. Never coerce with unary `+`.
44
+ - Coerce with `String()`, `Boolean()`, or a template literal, never with the wrapper constructors (`new String()`).
45
+ - Compare enum values explicitly, never by truthiness: the first member is `0`, which is falsy.
46
+ - Use `===` and `!==`. The one exception is `== null`, which matches both `null` and `undefined`.
47
+
48
+ ## Functions and classes
49
+
50
+ - Use function declarations for named functions, and arrow functions for callbacks and nested functions. Leave out function expressions.
51
+ - Pass an arrow function that forwards its arguments (`items.map((item) => parse(item))`) rather than a named function (`items.map(parse)`): the callee might pass extra arguments that the named function accepts with a different meaning.
52
+ - Give an arrow function a block body when its return value is unused.
53
+ - Use `this` only in constructors, methods, and arrow functions inside them. Never use it in a static context.
54
+ - Use rest parameters and spread instead of `arguments` and `Function.prototype.apply`.
55
+ - Keep default parameter values free of side effects.
56
+ - Mark properties that are never reassigned after the constructor `readonly`. Use parameter properties instead of copying constructor arguments by hand.
57
+ - Initialize every class property in its declaration or the constructor, including optional ones as `undefined`, so the object's shape never changes.
58
+ - Keep visibility as narrow as possible. Prefer a module-level function to a private method. Leave out the `public` modifier except on a mutable parameter property, and never use `obj['name']` to get around `private`.
59
+ - Keep getters free of side effects, and skip accessors that only pass a property through.
60
+ - Leave prototypes and built-in objects unmodified.
61
+
62
+ ## Control flow and errors
63
+
64
+ - Wrap every `if`, `for`, and `while` body in braces; only an `if` that fits on one line may skip them. Keep assignments out of conditions.
65
+ - Give every `switch` a final `default` group, and end every non-empty `case` with `break`, `return`, or `throw`. When a `switch` covers every member of a union or an enum, make `default` assign the value to a `never` variable, so adding a member fails the type check.
66
+ - Throw only `Error` objects or subclasses, created with `new`, and reject promises only with `Error`s. Prefer throwing to returning error objects.
67
+ - Treat a caught value as an `Error`, and skip defensive handling of non-`Error` throws unless a dependency actually throws them.
68
+ - Handle a caught error or comment why ignoring it is correct; never leave a `catch` block empty and silent.
69
+ - Keep a `try` block to the statements that can throw.
70
+ - Await every promise, return it, or handle its rejection. A promise left floating loses its errors; when fire-and-forget is intended, mark it with `void` and attach a `.catch`.
71
+
72
+ ## Language features to avoid
73
+
74
+ - `const enum` (use a plain `enum` or a union of literals), `with`, `eval`, the `Function(string)` constructor, and `debugger` in committed code.
75
+ - Semicolon-free code that relies on automatic semicolon insertion.
76
+ - Non-standard and proposal-stage JavaScript features, unless the project targets a runtime that ships them.
77
+ - New decorators. Use the decorators a framework defines, placed directly before the symbol they decorate.
78
+
79
+ ## Naming
80
+
81
+ - Use `UpperCamelCase` for classes, interfaces, types, enums, and type parameters; `lowerCamelCase` for variables, functions, methods, and properties; and `CONSTANT_CASE` for module-level constants and enum members.
82
+ - Write descriptive names without abbreviations a new reader wouldn't know. Leave type information out of names: no `I` prefix on interfaces, no Hungarian notation, and no `_` prefix or suffix for private members.
83
+ - Mark deprecated APIs with `@deprecated` and directions for migrating call sites.
@@ -0,0 +1,125 @@
1
+ ---
2
+ name: dot-roadmap
3
+ description: Turn a grilled plan into a roadmap of phases, each split into self-contained tasks.
4
+ argument-hint: "Path to the plan, if it isn't in this conversation"
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ # Roadmap
9
+
10
+ A roadmap splits a plan into **phases**, and each phase into **tasks**. A phase ends on a **milestone**: an observable state where the system works and could ship. A task is **self-contained**: a fresh agent session can build it from its file alone, and a reviewer can judge its diff in one sitting.
11
+
12
+ ## Repository conventions first
13
+
14
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Write tasks whose changes fit those conventions.
15
+
16
+ ## 1. Load the plan
17
+
18
+ Work from the plan in this conversation, usually the shared understanding a `dot-grill-me` session reached. If the user passed a path or URL, read it in full.
19
+
20
+ Synthesize; don't interview. If the plan still has unsettled decisions, list them and suggest `dot-grill-me` before you go on. Done when you can state the **destination** (what is true when the whole roadmap is done) and every decision the plan made.
21
+
22
+ ## 2. Gather facts
23
+
24
+ Read the code, tests, and configuration the plan touches. Note the modules each part of the plan reaches, the tests that already cover them, and any **prefactor**: a refactor that makes the later work easy. Done when you can name the files or modules each part of the plan changes.
25
+
26
+ ## 3. Cut phases
27
+
28
+ Group the work into phases, ordered so that:
29
+
30
+ - The first phase is a **tracer bullet**: the thinnest path through the whole system that proves the approach, so the riskiest unknown fails first.
31
+ - Prefactors come before the behavior that needs them.
32
+ - Each later phase builds on a milestone that already works.
33
+
34
+ Done when every phase has a milestone you can observe (a command's output, a passing test, a behavior in the UI), and the last milestone matches the destination.
35
+
36
+ ## 4. Split phases into tasks
37
+
38
+ Split each phase into tasks. Each task:
39
+
40
+ - Is a **vertical slice**: a narrow but complete path through every layer it needs, verifiable on its own.
41
+ - Keeps a refactor separate from a behavior change.
42
+ - Fits one fresh agent session and one reviewable diff, roughly a few hundred changed lines.
43
+ - Declares its **blockers**: the tasks that must be done first, by id (`2.3` is phase 2, task 3). A task without blockers can start now.
44
+
45
+ A **wide refactor**, one mechanical change that breaks many call sites at once, can't land as one green slice. Sequence it as **expand–contract**: add the new form beside the old, migrate callers in batches (one task each, blocked by the expand), then delete the old form in a task blocked by every batch.
46
+
47
+ Done when every requirement and decision from the plan belongs to exactly one task or to the roadmap's out-of-scope list, and every task has acceptance criteria that can fail.
48
+
49
+ ## 5. Review with the user
50
+
51
+ Show the breakdown compactly: each phase with its milestone, then its tasks as `id: title (blocked by: …) — goal`. Ask:
52
+
53
+ - Is the granularity right, or should some tasks merge or split?
54
+ - Does each blocker genuinely gate its task?
55
+ - Is anything in the plan missing, or in the wrong phase?
56
+
57
+ Iterate until the user approves. Write no files before approval.
58
+
59
+ ## 6. Write the roadmap
60
+
61
+ Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git check-ignore -q .tmp`: if `.tmp` isn't ignored, stop and tell the user rather than editing `.gitignore`.
62
+
63
+ ```
64
+ .tmp/roadmaps/<roadmap-slug>/
65
+ ├── README.md
66
+ ├── 01-<phase-slug>/
67
+ │ ├── 01-<task-slug>.md
68
+ │ └── 02-<task-slug>.md
69
+ └── 02-<phase-slug>/
70
+ └── 01-<task-slug>.md
71
+ ```
72
+
73
+ `README.md` is the index and the single source of truth for decisions; task files link to it instead of restating them:
74
+
75
+ ```markdown
76
+ # <Roadmap title>
77
+
78
+ **Destination:** <what is true when the roadmap is done>
79
+
80
+ ## Decisions
81
+
82
+ - <decision from the plan, one line each, with the reason when it isn't obvious>
83
+
84
+ ## Out of scope
85
+
86
+ - <work the plan ruled out>
87
+
88
+ ## Phases
89
+
90
+ ### 1. <Phase title>
91
+
92
+ **Milestone:** <observable state>
93
+
94
+ - [ ] [1.1 <Task title>](01-<phase-slug>/01-<task-slug>.md) (blocked by: none)
95
+ - [ ] [1.2 <Task title>](01-<phase-slug>/02-<task-slug>.md) (blocked by: 1.1)
96
+ ```
97
+
98
+ Each task file:
99
+
100
+ ```markdown
101
+ # <id>: <Task title>
102
+
103
+ **Roadmap:** [<Roadmap title>](../README.md)
104
+ **Goal:** <one sentence: the behavior this task makes work>
105
+ **Blocked by:** <ids, or "none">
106
+
107
+ ## Requirements
108
+
109
+ - <what the change must do, specific enough to build without the conversation>
110
+ - <files or modules it touches, when known>
111
+
112
+ ## Out of scope
113
+
114
+ - <nearby work that belongs to another task, with its id>
115
+
116
+ ## Acceptance criteria
117
+
118
+ - [ ] <checkable condition>
119
+
120
+ ## Verify
121
+
122
+ <the command or observation that proves the acceptance criteria>
123
+ ```
124
+
125
+ Done when every task file exists, `README.md` links each one, and each task reads complete without this conversation. End by telling the user the roadmap's path and the tasks they can start now.
@@ -1 +1 @@
1
- {"commit":"9ea2648"}
1
+ {"commit":"e82bea2"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@igorlau/dotagents",
3
- "version": "1.0.10",
3
+ "version": "1.0.12",
4
4
  "description": "Install a curated set of agent skills and rules into Claude Code, Codex, and GitHub Copilot.",
5
5
  "license": "MIT",
6
6
  "repository": {