@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/focused-implementation/SKILL.md

@@ -1,104 +1,104 @@
----
-name: focused-implementation
-description: Use when implementing a feature, change or fix in the code step, especially one that touches several files: turn the task into checkable goals, build it in small working slices, keep every changed line tied to the task, and record assumptions and side findings for the report instead of asking.
----
-
-# Focused implementation
-
-The reviewer should be able to read your diff and see the task in every line. Nobody answers questions during the run, so you decide, write the decision down, and keep going.
-
-Start with `project-orientation` if you have not done it in this run. When the spec has several changes, write the plan first with `implementation-plan`.
-
-## 1. Turn the task into goals you can check
-
-Before writing code, write a short list:
-
-```
-Goal: invoices show the VAT amount per line
-Checks:
-- [ ] unit test: 3 lines at 20% VAT give per-line VAT 2.00, 4.00, 0.50
-- [ ] invoice page renders a VAT column (component test or screenshot)
-- [ ] existing invoice tests still pass
-Assumptions:
-- Rounding per line, half up, as in src/money/round.ts (spec does not say)
-```
-
-- Take the acceptance criteria from the spec as they are. Each one becomes at least one check.
-- A vague goal ("make it work", "improve") becomes a concrete check you can run.
-- Where the task or spec is ambiguous, pick the reading that best matches the spec, the existing code and the smallest change. Write it under Assumptions. Do not stop to ask; `task-interview` says which open points deserve a question in the report.
-- If the task as written is impossible or contradicts the code (an API that does not exist, a field that is not stored), do the closest useful thing that stays inside the task, and explain the gap in the report.
-
-## 2. Choose the simplest design that meets the goals
-
-- Prefer the plain, obvious solution: a function call over an event bus, two similar components over a configurable framework for two cases. Three similar lines beat a premature abstraction.
-- No speculative features, options, flags or extension points that the task does not need.
-- Reuse what the project already has (helpers, components, error types, query builders) before writing new ones.
-- For a change that spans many modules or needs a real design decision, ask the `code-architect` agent for one concrete blueprint, then follow it unless you find a reason not to (and say why).
-
-## 3. Build in thin slices
-
-Work in slices that each leave the project working:
-
-1. Implement the smallest complete piece (vertical: from storage to API to UI for one case, rather than all of the storage first).
-2. Test it: write the test first where the project has tests (`test-driven-development`), then run the tests near the change.
-3. Check it builds and type-checks.
-4. Move to the next slice.
-
-Rules:
-- Do not write more than roughly 100 lines without running something.
-- Put the riskiest or least certain piece first, so a dead end shows up early.
-- Never leave the build broken between slices.
-- Commit a slice when it is green if that makes the history clearer (`clean-commits`); one commit at the end is also fine.
-- New behaviour defaults to the safe, conservative option (off, opt-in, read-only) unless the task says otherwise.
-
-## 4. Keep changes surgical
-
-Every changed line should trace back to the task.
-
-- Do not reformat, rename, reorder imports or "modernise" code you are not otherwise changing.
-- Do not delete comments, code or tests you do not fully understand.
-- Match the surrounding style even if you would write it differently.
-- Clean up what your own change made unused (imports, helpers, variables). Leave older dead code alone.
-- When you notice something wrong outside the task, do not fix it. Add it to a "Noticed, not changed" list for the report:
-
-```
-Noticed, not changed:
-- src/utils/format.ts: unused import of `dayjs` (unrelated)
-- Login form shows the raw server error text (separate task)
-```
-
-Exception: if the task cannot be done correctly without touching it (the bug you are fixing lives there), change it and say why.
-
-## 5. Flag these in the report
-
-Do them only when the task needs them, choose the smaller option, and list them in the report so the reviewer looks closely:
-
-- New dependencies, or upgrades of existing ones.
-- Database schema changes or migrations (follow `safe-database-changes`).
-- Changes to authentication, authorisation, sessions, CORS, uploads, rate limits, roles or permissions.
-- New external services or new kinds of stored sensitive data.
-- Changes to a public API, a shared contract, CI config or build config.
-- Deleting files, features or tests.
-- Changes in a repository that the task did not obviously involve.
-
-Never: commit secrets, edit vendored or generated files by hand (regenerate them the way the project does), weaken or delete a failing test to get green, or disable lint rules to silence your own code.
-
-## 6. Finish
-
-1. Tidy your own diff: remove debug output, leftover TODOs you created, commented-out code. For a large change, the `code-simplifier` agent can do a behaviour-preserving pass over the changed files.
-2. Run `verification-before-completion`.
-3. Commit with `clean-commits`.
-4. Write the report: what changed, how it was checked (commands and results), assumptions, flagged items, noticed-not-changed list, anything left open.
-
-## Common mistakes
-
-| Thought | What to do instead |
-|---|---|
-| "While I'm here I'll clean this up" | Note it under "Noticed, not changed". |
-| "I'll test it all at the end" | Test each slice; a bug in slice 1 makes slices 2 to 5 wrong. |
-| "Let me make it configurable, just in case" | Build what the task needs; add options when a second case exists. |
-| "The spec is unclear, I'll wait" | Pick the most reasonable reading, write it under Assumptions, continue. |
-| "This refactor is small enough to include" | Keep refactors out of feature changes unless the task needs them. |
-| "Lint fails on my line, I'll add an ignore comment" | Fix the code; ignore comments only where the project already uses them for the same case, with a reason. |
-
-Sources: addyosmani/agent-skills (MIT, commit aeac41d) incremental-implementation, plus ideas restated from the Karpathy coding guidelines. Changed: rewritten for unattended runs.
+---
+name: focused-implementation
+description: Use when implementing a feature, change or fix in the code step, especially one that touches several files: turn the task into checkable goals, build it in small working slices, keep every changed line tied to the task, and record assumptions and side findings for the report instead of asking.
+---
+
+# Focused implementation
+
+The reviewer should be able to read your diff and see the task in every line. Nobody answers questions during the run, so you decide, write the decision down, and keep going.
+
+Start with `project-orientation` if you have not done it in this run. When the spec has several changes, write the plan first with `implementation-plan`.
+
+## 1. Turn the task into goals you can check
+
+Before writing code, write a short list:
+
+```
+Goal: invoices show the VAT amount per line
+Checks:
+- [ ] unit test: 3 lines at 20% VAT give per-line VAT 2.00, 4.00, 0.50
+- [ ] invoice page renders a VAT column (component test or screenshot)
+- [ ] existing invoice tests still pass
+Assumptions:
+- Rounding per line, half up, as in src/money/round.ts (spec does not say)
+```
+
+- Take the acceptance criteria from the spec as they are. Each one becomes at least one check.
+- A vague goal ("make it work", "improve") becomes a concrete check you can run.
+- Where the task or spec is ambiguous, pick the reading that best matches the spec, the existing code and the smallest change. Write it under Assumptions. Do not stop to ask; `task-interview` says which open points deserve a question in the report.
+- If the task as written is impossible or contradicts the code (an API that does not exist, a field that is not stored), do the closest useful thing that stays inside the task, and explain the gap in the report.
+
+## 2. Choose the simplest design that meets the goals
+
+- Prefer the plain, obvious solution: a function call over an event bus, two similar components over a configurable framework for two cases. Three similar lines beat a premature abstraction.
+- No speculative features, options, flags or extension points that the task does not need.
+- Reuse what the project already has (helpers, components, error types, query builders) before writing new ones.
+- For a change that spans many modules or needs a real design decision, ask the `code-architect` agent for one concrete blueprint, then follow it unless you find a reason not to (and say why).
+
+## 3. Build in thin slices
+
+Work in slices that each leave the project working:
+
+1. Implement the smallest complete piece (vertical: from storage to API to UI for one case, rather than all of the storage first).
+2. Test it: write the test first where the project has tests (`test-driven-development`), then run the tests near the change.
+3. Check it builds and type-checks.
+4. Move to the next slice.
+
+Rules:
+- Do not write more than roughly 100 lines without running something.
+- Put the riskiest or least certain piece first, so a dead end shows up early.
+- Never leave the build broken between slices.
+- Commit a slice when it is green if that makes the history clearer (`clean-commits`); one commit at the end is also fine.
+- New behaviour defaults to the safe, conservative option (off, opt-in, read-only) unless the task says otherwise.
+
+## 4. Keep changes surgical
+
+Every changed line should trace back to the task.
+
+- Do not reformat, rename, reorder imports or "modernise" code you are not otherwise changing.
+- Do not delete comments, code or tests you do not fully understand.
+- Match the surrounding style even if you would write it differently.
+- Clean up what your own change made unused (imports, helpers, variables). Leave older dead code alone.
+- When you notice something wrong outside the task, do not fix it. Add it to a "Noticed, not changed" list for the report:
+
+```
+Noticed, not changed:
+- src/utils/format.ts: unused import of `dayjs` (unrelated)
+- Login form shows the raw server error text (separate task)
+```
+
+Exception: if the task cannot be done correctly without touching it (the bug you are fixing lives there), change it and say why.
+
+## 5. Flag these in the report
+
+Do them only when the task needs them, choose the smaller option, and list them in the report so the reviewer looks closely:
+
+- New dependencies, or upgrades of existing ones.
+- Database schema changes or migrations (follow `safe-database-changes`).
+- Changes to authentication, authorisation, sessions, CORS, uploads, rate limits, roles or permissions.
+- New external services or new kinds of stored sensitive data.
+- Changes to a public API, a shared contract, CI config or build config.
+- Deleting files, features or tests.
+- Changes in a repository that the task did not obviously involve.
+
+Never: commit secrets, edit vendored or generated files by hand (regenerate them the way the project does), weaken or delete a failing test to get green, or disable lint rules to silence your own code.
+
+## 6. Finish
+
+1. Tidy your own diff: remove debug output, leftover TODOs you created, commented-out code. For a large change, the `code-simplifier` agent can do a behaviour-preserving pass over the changed files.
+2. Run `verification-before-completion`.
+3. Commit with `clean-commits`.
+4. Write the report: what changed, how it was checked (commands and results), assumptions, flagged items, noticed-not-changed list, anything left open.
+
+## Common mistakes
+
+| Thought | What to do instead |
+|---|---|
+| "While I'm here I'll clean this up" | Note it under "Noticed, not changed". |
+| "I'll test it all at the end" | Test each slice; a bug in slice 1 makes slices 2 to 5 wrong. |
+| "Let me make it configurable, just in case" | Build what the task needs; add options when a second case exists. |
+| "The spec is unclear, I'll wait" | Pick the most reasonable reading, write it under Assumptions, continue. |
+| "This refactor is small enough to include" | Keep refactors out of feature changes unless the task needs them. |
+| "Lint fails on my line, I'll add an ignore comment" | Fix the code; ignore comments only where the project already uses them for the same case, with a reason. |
+
+Sources: addyosmani/agent-skills (MIT, commit aeac41d) incremental-implementation, plus ideas restated from the Karpathy coding guidelines. Changed: rewritten for unattended runs.

package/library/skills/implementation-plan/SKILL.md

@@ -1,66 +1,66 @@
----
-name: implementation-plan
-description: Use at the start of a code step when the spec or task touches more than one file or more than one repository: turn it into an ordered plan of small tasks with exact files, the interfaces passed between them, the checks that prove each one, and a review focus of the inputs no test covers yet.
----
-
-# Implementation plan
-
-A plan is the set of decisions an implementer cannot make alone: which files, which names and signatures, which values from the spec, which tests prove each step. Write those down, nothing more. A plan longer than the code it describes has written the code instead.
-
-Start with `project-orientation` if you have not done it in this run. Keep the plan in your working notes; it does not go into the repository unless the project asks for plans there.
-
-## 1. Read the spec as the contract
-
-- The acceptance criteria (AC-1, AC-2 and so on) are the finish line. Each one must end up proven by a test or a check.
-- Out of scope is a hard limit: nothing from it goes into the plan.
-- Decisions, assumptions and the code map are settled: follow them. If the code contradicts one, note it for the report and pick the reading closest to the spec.
-- Values the spec pins (texts, limits, names, status codes) are copied verbatim into a "Constraints" list at the top of the plan.
-
-## 2. Map the files
-
-List every file you will create or change, with one line on its responsibility. Files that change together live together; follow the project's existing layout.
-
-## 3. Order the tasks
-
-Each task is the smallest unit with its own test cycle that a reviewer could accept or reject on its own:
-
-```
-Task 2: CSV export endpoint
-Files: create server/api/boards/[id]/export.get.ts; test test/boardExport.test.ts
-Consumes: canSeeBoard(userId, boardId) from server/utils/boardAccess.ts
-Produces: GET /api/boards/:id/export -> text/csv, header "Title,Status,Owner"
-Proves: AC-1, AC-2
-Steps:
-  1. Test: 3 tasks give 4 lines; no access gives 404 (fails first)
-  2. Implement exportCsv(boardId: number): string and the route
-  3. Run: pnpm test test/boardExport.test.ts -> 2 passed
-```
-
-- Order by dependency: a task uses only what earlier tasks or the existing code provide. Put the riskiest or least certain task as early as its dependencies allow.
-- **Interfaces:** write Consumes and Produces with exact names, parameters, return types and data shapes. This is how the next task learns the names; check that every name used later is produced earlier.
-- **Steps:** each step is one action with a checkable result, and lets you write exactly one reasonable thing. Lines that decide nothing ("handle edge cases", "add validation", "write tests") are gaps: replace them with the case, the rule or the test name.
-- **Tests at the highest seam** that covers the behaviour: an endpoint, a page or a public function, not private helpers. Follow `test-driven-development`.
-
-## 4. Verification
-
-Split it in two:
-
-- **Automated:** the exact commands (tests, type check, lint, build) and what passing looks like. Take them from the spec's test plan and from `project-orientation`.
-- **Manual:** what a person does and sees, naming the page or command. For interface work, the screens to render with `ui-testing` or `design-review`.
-
-Map every acceptance criterion to the task and the check that proves it. A criterion without a check is a gap: add the test.
-
-## 5. Review focus
-
-Write up to five input classes or failure modes the spec implies but no planned test exercises, most likely to bite a person first: an empty list, a very long name, a second click, an expired session, a slow network. The spec's silence on an input is not permission for that input to break the program. For each line, add the test to the task that owns the code, or say in the report why it is left.
-
-## 6. Self-check before coding
-
-1. **Coverage:** every criterion has a task and a check; every task proves a criterion.
-2. **Names:** names and signatures match between Produces and Consumes.
-3. **Scope:** nothing from out of scope, nothing the spec did not ask for.
-4. **Proportion:** the plan is shorter than the code it describes.
-
-Then build it with `focused-implementation`, one task at a time, and finish with `verification-before-completion`. Put the plan's Review Focus and any deviations from the spec in the report.
-
-Sources: adapted from obra/superpowers writing-plans (MIT, commit b739a8a), the plan template and ready-for-development rules of bmad-code-org/BMAD-METHOD (MIT, commit 61e01f8), humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67) and mattpocock/skills to-spec testing seams (MIT, commit 5beb35b). Changed: condensed into one process for unattended code steps, the plan stays in working notes, execution choices removed.
+---
+name: implementation-plan
+description: Use at the start of a code step when the spec or task touches more than one file or more than one repository: turn it into an ordered plan of small tasks with exact files, the interfaces passed between them, the checks that prove each one, and a review focus of the inputs no test covers yet.
+---
+
+# Implementation plan
+
+A plan is the set of decisions an implementer cannot make alone: which files, which names and signatures, which values from the spec, which tests prove each step. Write those down, nothing more. A plan longer than the code it describes has written the code instead.
+
+Start with `project-orientation` if you have not done it in this run. Keep the plan in your working notes; it does not go into the repository unless the project asks for plans there.
+
+## 1. Read the spec as the contract
+
+- The acceptance criteria (AC-1, AC-2 and so on) are the finish line. Each one must end up proven by a test or a check.
+- Out of scope is a hard limit: nothing from it goes into the plan.
+- Decisions, assumptions and the code map are settled: follow them. If the code contradicts one, note it for the report and pick the reading closest to the spec.
+- Values the spec pins (texts, limits, names, status codes) are copied verbatim into a "Constraints" list at the top of the plan.
+
+## 2. Map the files
+
+List every file you will create or change, with one line on its responsibility. Files that change together live together; follow the project's existing layout.
+
+## 3. Order the tasks
+
+Each task is the smallest unit with its own test cycle that a reviewer could accept or reject on its own:
+
+```
+Task 2: CSV export endpoint
+Files: create server/api/boards/[id]/export.get.ts; test test/boardExport.test.ts
+Consumes: canSeeBoard(userId, boardId) from server/utils/boardAccess.ts
+Produces: GET /api/boards/:id/export -> text/csv, header "Title,Status,Owner"
+Proves: AC-1, AC-2
+Steps:
+  1. Test: 3 tasks give 4 lines; no access gives 404 (fails first)
+  2. Implement exportCsv(boardId: number): string and the route
+  3. Run: pnpm test test/boardExport.test.ts -> 2 passed
+```
+
+- Order by dependency: a task uses only what earlier tasks or the existing code provide. Put the riskiest or least certain task as early as its dependencies allow.
+- **Interfaces:** write Consumes and Produces with exact names, parameters, return types and data shapes. This is how the next task learns the names; check that every name used later is produced earlier.
+- **Steps:** each step is one action with a checkable result, and lets you write exactly one reasonable thing. Lines that decide nothing ("handle edge cases", "add validation", "write tests") are gaps: replace them with the case, the rule or the test name.
+- **Tests at the highest seam** that covers the behaviour: an endpoint, a page or a public function, not private helpers. Follow `test-driven-development`.
+
+## 4. Verification
+
+Split it in two:
+
+- **Automated:** the exact commands (tests, type check, lint, build) and what passing looks like. Take them from the spec's test plan and from `project-orientation`.
+- **Manual:** what a person does and sees, naming the page or command. For interface work, the screens to render with `ui-testing` or `design-review`.
+
+Map every acceptance criterion to the task and the check that proves it. A criterion without a check is a gap: add the test.
+
+## 5. Review focus
+
+Write up to five input classes or failure modes the spec implies but no planned test exercises, most likely to bite a person first: an empty list, a very long name, a second click, an expired session, a slow network. The spec's silence on an input is not permission for that input to break the program. For each line, add the test to the task that owns the code, or say in the report why it is left.
+
+## 6. Self-check before coding
+
+1. **Coverage:** every criterion has a task and a check; every task proves a criterion.
+2. **Names:** names and signatures match between Produces and Consumes.
+3. **Scope:** nothing from out of scope, nothing the spec did not ask for.
+4. **Proportion:** the plan is shorter than the code it describes.
+
+Then build it with `focused-implementation`, one task at a time, and finish with `verification-before-completion`. Put the plan's Review Focus and any deviations from the spec in the report.
+
+Sources: adapted from obra/superpowers writing-plans (MIT, commit b739a8a), the plan template and ready-for-development rules of bmad-code-org/BMAD-METHOD (MIT, commit 61e01f8), humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67) and mattpocock/skills to-spec testing seams (MIT, commit 5beb35b). Changed: condensed into one process for unattended code steps, the plan stays in working notes, execution choices removed.