estimetry 0.0.0-stage → 0.1.0
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/CHANGELOG.md +20 -0
- package/LICENSE +21 -0
- package/README.md +416 -2
- package/README.ru.md +417 -0
- package/dist/application/contracts/command-content.js +2 -0
- package/dist/application/contracts/file-change.js +12 -0
- package/dist/application/contracts/flow.js +2 -0
- package/dist/application/contracts/hook-adapter.js +2 -0
- package/dist/application/contracts/install-blocked.js +6 -0
- package/dist/application/contracts/registries.js +2 -0
- package/dist/application/contracts/session-logs.js +16 -0
- package/dist/application/contracts/stack-detector.js +2 -0
- package/dist/application/contracts/tool-adapter.js +2 -0
- package/dist/application/estimetry.js +165 -0
- package/dist/application/hooks/activity-recorder.js +48 -0
- package/dist/application/hooks/bind-session.js +49 -0
- package/dist/application/hooks/change-completions.js +146 -0
- package/dist/application/hooks/checkpoint-snapshot.js +37 -0
- package/dist/application/hooks/checkpoints.js +57 -0
- package/dist/application/hooks/commit-records.js +83 -0
- package/dist/application/hooks/context-limit.js +7 -0
- package/dist/application/hooks/flow-plans.js +115 -0
- package/dist/application/hooks/hook-call.js +2 -0
- package/dist/application/hooks/hook-context.js +61 -0
- package/dist/application/hooks/journal-entry.js +15 -0
- package/dist/application/hooks/pending-proposal.js +46 -0
- package/dist/application/hooks/progress-log.js +43 -0
- package/dist/application/hooks/prompt-context.js +18 -0
- package/dist/application/hooks/receive-hook.js +41 -0
- package/dist/application/hooks/receive-session-hook.js +53 -0
- package/dist/application/hooks/recent-sessions.js +25 -0
- package/dist/application/hooks/session-end-import.js +43 -0
- package/dist/application/hooks/session-start-context.js +43 -0
- package/dist/application/hooks/session-task.js +80 -0
- package/dist/application/hooks/task-facts.js +28 -0
- package/dist/application/hooks/upgrade-notice.js +21 -0
- package/dist/application/ports/author-provider.js +2 -0
- package/dist/application/ports/calibration-settings.js +2 -0
- package/dist/application/ports/calibration-store.js +2 -0
- package/dist/application/ports/card-store.js +2 -0
- package/dist/application/ports/checkpoint-state.js +2 -0
- package/dist/application/ports/clock.js +2 -0
- package/dist/application/ports/close-proposals.js +2 -0
- package/dist/application/ports/code-measurer.js +2 -0
- package/dist/application/ports/command-locator.js +2 -0
- package/dist/application/ports/commit-hook-installer.js +2 -0
- package/dist/application/ports/error-reporter.js +2 -0
- package/dist/application/ports/estimate-reader.js +2 -0
- package/dist/application/ports/event-journal.js +2 -0
- package/dist/application/ports/file-change.js +12 -0
- package/dist/application/ports/git-excludes.js +2 -0
- package/dist/application/ports/git-snapshot.js +2 -0
- package/dist/application/ports/id-generator.js +2 -0
- package/dist/application/ports/install-versions.js +2 -0
- package/dist/application/ports/log-import-state.js +2 -0
- package/dist/application/ports/measurement-settings.js +2 -0
- package/dist/application/ports/progress-state.js +2 -0
- package/dist/application/ports/project-config-file.js +2 -0
- package/dist/application/ports/project-files.js +2 -0
- package/dist/application/ports/project-locator.js +2 -0
- package/dist/application/ports/project-paths.js +2 -0
- package/dist/application/ports/project-plans.js +2 -0
- package/dist/application/ports/session-bindings.js +31 -0
- package/dist/application/ports/sharing-preference.js +5 -0
- package/dist/application/ports/task-status-reader.js +2 -0
- package/dist/application/ports/task-type-catalog.js +2 -0
- package/dist/application/ports/workspace-locator.js +2 -0
- package/dist/application/project/init-defaults.js +27 -0
- package/dist/application/project/init-project.js +109 -0
- package/dist/application/project/install-copy.js +90 -0
- package/dist/application/project/install-dependencies.js +2 -0
- package/dist/application/project/install-outdated.js +24 -0
- package/dist/application/project/resolve-current-project.js +103 -0
- package/dist/application/project/show-init-choices.js +30 -0
- package/dist/application/project/show-upgrade-plan.js +23 -0
- package/dist/application/project/stack.js +41 -0
- package/dist/application/project/upgrade-plan.js +94 -0
- package/dist/application/project/upgrade-projects.js +29 -0
- package/dist/application/shared/change-archives.js +23 -0
- package/dist/application/shared/event-meta-source.js +27 -0
- package/dist/application/shared/install-outdated.js +24 -0
- package/dist/application/shared/journal-entry.js +21 -0
- package/dist/application/shared/retry.js +17 -0
- package/dist/application/shared/working-copy.js +5 -0
- package/dist/application/task/attach-task.js +36 -0
- package/dist/application/task/author-aliases.js +22 -0
- package/dist/application/task/bind-session.js +50 -0
- package/dist/application/task/card-builder.js +89 -0
- package/dist/application/task/change-parallel-mode.js +47 -0
- package/dist/application/task/close-task.js +53 -0
- package/dist/application/task/closing-follow-up.js +63 -0
- package/dist/application/task/closing-records.js +77 -0
- package/dist/application/task/code-volume-service.js +87 -0
- package/dist/application/task/create-task.js +30 -0
- package/dist/application/task/derived-steps.js +20 -0
- package/dist/application/task/estimate-file.js +16 -0
- package/dist/application/task/estimate-query.js +8 -0
- package/dist/application/task/find-revision-candidates.js +36 -0
- package/dist/application/task/find-similar-tasks.js +95 -0
- package/dist/application/task/import-session-logs.js +146 -0
- package/dist/application/task/list-tasks.js +19 -0
- package/dist/application/task/plan-revised.js +7 -0
- package/dist/application/task/plan-snapshots.js +62 -0
- package/dist/application/task/rebuild.js +36 -0
- package/dist/application/task/record-extra.js +25 -0
- package/dist/application/task/record-manual-time.js +40 -0
- package/dist/application/task/record-retro.js +43 -0
- package/dist/application/task/renegotiate.js +66 -0
- package/dist/application/task/reopen-task.js +31 -0
- package/dist/application/task/repair-revision.js +22 -0
- package/dist/application/task/resolve-active-task.js +50 -0
- package/dist/application/task/revise-estimate.js +95 -0
- package/dist/application/task/revision-records.js +33 -0
- package/dist/application/task/save-estimate.js +31 -0
- package/dist/application/task/session-window.js +41 -0
- package/dist/application/task/show-calibration.js +72 -0
- package/dist/application/task/show-close-summary.js +28 -0
- package/dist/application/task/show-renegotiation-target.js +14 -0
- package/dist/application/task/show-status.js +126 -0
- package/dist/application/task/show-task.js +19 -0
- package/dist/application/task/start-task.js +46 -0
- package/dist/application/task/task-cards.js +110 -0
- package/dist/application/task/task-changes.js +9 -0
- package/dist/application/task/task-closing.js +21 -0
- package/dist/application/task/task-measurement.js +95 -0
- package/dist/application/task/task-plan-progress.js +81 -0
- package/dist/application/task/task-view.js +32 -0
- package/dist/bootstrap/container.js +137 -0
- package/dist/bootstrap/hook-receiver.js +130 -0
- package/dist/bootstrap/main.js +42 -0
- package/dist/bootstrap/package-version.js +7 -0
- package/dist/domain/calibration/applicable-coefficient.js +26 -0
- package/dist/domain/calibration/calibration.js +184 -0
- package/dist/domain/calibration/code-and-parts.js +95 -0
- package/dist/domain/calibration/other-authors.js +6 -0
- package/dist/domain/calibration/statistics.js +14 -0
- package/dist/domain/calibration/task-ratio.js +84 -0
- package/dist/domain/card/build-card.js +68 -0
- package/dist/domain/card/card-errors.js +9 -0
- package/dist/domain/card/card-sections.js +152 -0
- package/dist/domain/card/card-v1.js +28 -0
- package/dist/domain/card/card-v2.js +12 -0
- package/dist/domain/card/card.js +6 -0
- package/dist/domain/card/estimate-query.js +17 -0
- package/dist/domain/card/extra-tallies.js +35 -0
- package/dist/domain/card/revision-facts.js +18 -0
- package/dist/domain/code/code-classes.js +32 -0
- package/dist/domain/code/code-volume.js +76 -0
- package/dist/domain/estimate/code-volume.js +31 -0
- package/dist/domain/estimate/estimate-part.js +47 -0
- package/dist/domain/estimate/estimate-query.js +15 -0
- package/dist/domain/estimate/estimate-revision.js +70 -0
- package/dist/domain/estimate/estimate.js +109 -0
- package/dist/domain/estimate/invalid-estimate.js +14 -0
- package/dist/domain/estimate/lost-window.js +48 -0
- package/dist/domain/estimate/part-kind.js +10 -0
- package/dist/domain/estimate/plan-changes.js +9 -0
- package/dist/domain/estimate/stack-labels.js +28 -0
- package/dist/domain/estimate/three-point-estimate.js +38 -0
- package/dist/domain/measurement/activity-events.js +160 -0
- package/dist/domain/measurement/collector.js +191 -0
- package/dist/domain/measurement/duration.js +76 -0
- package/dist/domain/measurement/effort-calculator.js +140 -0
- package/dist/domain/measurement/effort-report.js +3 -0
- package/dist/domain/measurement/extra.js +65 -0
- package/dist/domain/measurement/idle-policy.js +23 -0
- package/dist/domain/measurement/interval-set.js +80 -0
- package/dist/domain/measurement/interval.js +30 -0
- package/dist/domain/measurement/log-boundaries.js +2 -0
- package/dist/domain/measurement/log-matching.js +37 -0
- package/dist/domain/measurement/main-stream.js +218 -0
- package/dist/domain/measurement/manual-time.js +70 -0
- package/dist/domain/measurement/parallel-mode.js +57 -0
- package/dist/domain/measurement/prepared-events.js +55 -0
- package/dist/domain/measurement/run.js +93 -0
- package/dist/domain/measurement/session-id.js +22 -0
- package/dist/domain/measurement/session-windows.js +33 -0
- package/dist/domain/measurement/subagent-stream.js +53 -0
- package/dist/domain/measurement/timeline.js +30 -0
- package/dist/domain/progress/checkbox-walk.js +93 -0
- package/dist/domain/progress/part-facts.js +222 -0
- package/dist/domain/progress/plan-exclusions.js +36 -0
- package/dist/domain/progress/plan-progress.js +102 -0
- package/dist/domain/progress/progress-record-parser.js +261 -0
- package/dist/domain/progress/progress-records.js +31 -0
- package/dist/domain/progress/session-log.js +81 -0
- package/dist/domain/progress/task-plan.js +52 -0
- package/dist/domain/project/project-id.js +40 -0
- package/dist/domain/project/project-repository.js +14 -0
- package/dist/domain/project/project.js +80 -0
- package/dist/domain/shared/author.js +22 -0
- package/dist/domain/shared/calendar-date.js +40 -0
- package/dist/domain/shared/domain-error.js +14 -0
- package/dist/domain/shared/event-envelope.js +2 -0
- package/dist/domain/shared/kebab-case.js +12 -0
- package/dist/domain/shared/timestamp.js +31 -0
- package/dist/domain/similarity/similarity.js +57 -0
- package/dist/domain/task/revision-candidates.js +9 -0
- package/dist/domain/task/task-apply.js +65 -0
- package/dist/domain/task/task-closures.js +52 -0
- package/dist/domain/task/task-creation.js +23 -0
- package/dist/domain/task/task-errors.js +89 -0
- package/dist/domain/task/task-event-log.js +34 -0
- package/dist/domain/task/task-events.js +32 -0
- package/dist/domain/task/task-id.js +37 -0
- package/dist/domain/task/task-records.js +2 -0
- package/dist/domain/task/task-repository.js +2 -0
- package/dist/domain/task/task-retro.js +29 -0
- package/dist/domain/task/task-revisions.js +122 -0
- package/dist/domain/task/task-snapshot.js +148 -0
- package/dist/domain/task/task-state.js +38 -0
- package/dist/domain/task/task-status.js +18 -0
- package/dist/domain/task/task-type.js +34 -0
- package/dist/domain/task/task-work-records.js +36 -0
- package/dist/domain/task/task.js +325 -0
- package/dist/domain/usage/task-usage.js +86 -0
- package/dist/infrastructure/fs/atomic-yaml.js +63 -0
- package/dist/infrastructure/fs/file-lock.js +98 -0
- package/dist/infrastructure/fs/fs-project-locator.js +58 -0
- package/dist/infrastructure/fs/jsonl.js +50 -0
- package/dist/infrastructure/fs/node-project-files.js +160 -0
- package/dist/infrastructure/fs/storage-layout.js +105 -0
- package/dist/infrastructure/fs/worktree.js +43 -0
- package/dist/infrastructure/git/fs-git-head.js +69 -0
- package/dist/infrastructure/git/git-cli.js +41 -0
- package/dist/infrastructure/git/git-code-measurer.js +90 -0
- package/dist/infrastructure/git/git-commit-hook-installer.js +131 -0
- package/dist/infrastructure/git/git-excludes-file.js +48 -0
- package/dist/infrastructure/git/git-snapshots.js +62 -0
- package/dist/infrastructure/persistence/file-close-proposals.js +76 -0
- package/dist/infrastructure/persistence/file-project-repository.js +67 -0
- package/dist/infrastructure/persistence/file-task-repository.js +143 -0
- package/dist/infrastructure/persistence/file-task-status-reader.js +71 -0
- package/dist/infrastructure/persistence/json-calibration-store.js +28 -0
- package/dist/infrastructure/persistence/jsonl-event-journal.js +93 -0
- package/dist/infrastructure/persistence/records.js +265 -0
- package/dist/infrastructure/persistence/snapshot-task-reader.js +23 -0
- package/dist/infrastructure/persistence/yaml-card-store.js +91 -0
- package/dist/infrastructure/persistence/yaml-config-store.js +118 -0
- package/dist/infrastructure/persistence/yaml-estimate-reader.js +240 -0
- package/dist/infrastructure/persistence/yaml-install-versions.js +40 -0
- package/dist/infrastructure/persistence/yaml-log-import-state.js +61 -0
- package/dist/infrastructure/persistence/yaml-progress-state.js +40 -0
- package/dist/infrastructure/persistence/yaml-project-config-file.js +58 -0
- package/dist/infrastructure/persistence/yaml-session-store.js +122 -0
- package/dist/infrastructure/system/file-error-reporter.js +39 -0
- package/dist/infrastructure/system/path-command-locator.js +31 -0
- package/dist/infrastructure/system/random-id-generator.js +7 -0
- package/dist/infrastructure/system/system-clock.js +7 -0
- package/dist/integrations/flows/none/none-flow.js +10 -0
- package/dist/integrations/flows/openspec/openspec-flow.js +45 -0
- package/dist/integrations/flows/openspec/openspec-plan.js +91 -0
- package/dist/integrations/flows/registry.js +18 -0
- package/dist/integrations/stack/compose-detector.js +28 -0
- package/dist/integrations/stack/dart-detector.js +21 -0
- package/dist/integrations/stack/go-detector.js +10 -0
- package/dist/integrations/stack/jvm-detector.js +28 -0
- package/dist/integrations/stack/node-detector.js +33 -0
- package/dist/integrations/stack/python-detector.js +10 -0
- package/dist/integrations/stack/registry.js +11 -0
- package/dist/integrations/tools/claude-code/claude-code-adapter.js +119 -0
- package/dist/integrations/tools/claude-code/claude-md.js +28 -0
- package/dist/integrations/tools/claude-code/hook-events.js +18 -0
- package/dist/integrations/tools/claude-code/hook-settings.js +127 -0
- package/dist/integrations/tools/claude-code/hook-translation.js +125 -0
- package/dist/integrations/tools/claude-code/importer/claude-code-logs.js +121 -0
- package/dist/integrations/tools/claude-code/importer/log-lines.js +38 -0
- package/dist/integrations/tools/claude-code/importer/log-parser.js +289 -0
- package/dist/integrations/tools/claude-code/skill-file.js +31 -0
- package/dist/integrations/tools/content/commands.js +178 -0
- package/dist/integrations/tools/git/git-hooks.js +16 -0
- package/dist/integrations/tools/hook-adapters.js +12 -0
- package/dist/integrations/tools/registry.js +19 -0
- package/dist/integrations/tools/session-log-readers.js +12 -0
- package/dist/interface/cli/cli-context.js +6 -0
- package/dist/interface/cli/cli-output.js +2 -0
- package/dist/interface/cli/commands/attach-command.js +20 -0
- package/dist/interface/cli/commands/calibrate-command.js +21 -0
- package/dist/interface/cli/commands/close-commands.js +149 -0
- package/dist/interface/cli/commands/estimate-command.js +77 -0
- package/dist/interface/cli/commands/extra-command.js +28 -0
- package/dist/interface/cli/commands/hook-command.js +57 -0
- package/dist/interface/cli/commands/init-command.js +86 -0
- package/dist/interface/cli/commands/manual-command.js +29 -0
- package/dist/interface/cli/commands/parallel-command.js +35 -0
- package/dist/interface/cli/commands/similar-command.js +23 -0
- package/dist/interface/cli/commands/start-command.js +23 -0
- package/dist/interface/cli/commands/status-command.js +15 -0
- package/dist/interface/cli/commands/task-commands.js +42 -0
- package/dist/interface/cli/commands/upgrade-command.js +51 -0
- package/dist/interface/cli/exit-codes.js +44 -0
- package/dist/interface/cli/help-command.js +16 -0
- package/dist/interface/cli/help.js +128 -0
- package/dist/interface/cli/parse-input.js +54 -0
- package/dist/interface/cli/presenters/json-presenter.js +30 -0
- package/dist/interface/cli/presenters/presenter.js +2 -0
- package/dist/interface/cli/presenters/text/closing-text.js +106 -0
- package/dist/interface/cli/presenters/text/estimate-text.js +185 -0
- package/dist/interface/cli/presenters/text/format.js +41 -0
- package/dist/interface/cli/presenters/text/notices-text.js +21 -0
- package/dist/interface/cli/presenters/text/task-text.js +135 -0
- package/dist/interface/cli/presenters/text/upgrade-text.js +47 -0
- package/dist/interface/cli/presenters/text-presenter.js +106 -0
- package/dist/interface/cli/program.js +63 -0
- package/dist/interface/cli/prompts.js +110 -0
- package/package.json +58 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to estimetry. Versions follow [semantic versioning](https://semver.org); while at 0.x, a minor version may change commands or the storage format, and says so here.
|
|
4
|
+
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
## 0.1.0 — 2026-11-12
|
|
8
|
+
|
|
9
|
+
The first public version: estimates of AI-agent development work compared with the actual effort, and that experience reused in the next estimate. Claude Code is the only supported AI tool.
|
|
10
|
+
|
|
11
|
+
- `estimetry init` sets up a project: Claude Code hooks, the `/emt-…` skills, the development process (OpenSpec or none) and an optional `post-commit` hook.
|
|
12
|
+
- Tasks and estimates by parts of the plan: `emt task`, `emt estimate save`, `emt estimate revise` for a task in progress.
|
|
13
|
+
- The fact of a task measured from the hooks: the time of the agents and your own, manual time, extra work, parallel sessions, and a range of how certain the fact is. Session logs of Claude Code narrow the range and add tokens and cost.
|
|
14
|
+
- Plan progress by archived OpenSpec changes and checkpoints.
|
|
15
|
+
- Closing, retro, the card of a closed task and personal calibration: `emt close`, `emt retro`, `emt reopen`, `emt rebuild`.
|
|
16
|
+
- Estimates from past tasks: `emt similar` and `emt calibrate`, used by `/emt-estimate`.
|
|
17
|
+
- Work in git worktrees: a worktree belongs to the project of its main working copy, and the plan, checkpoints and code volume of a task are read in the working copy that holds its changes, also when the session runs in the main working copy. `emt attach --session` counts the first task of a session from the start of the task.
|
|
18
|
+
- `emt upgrade`: after updating estimetry, sets it up again in every project on this machine with one command, after showing the plan and asking. The session start tells the agent to suggest it when a project was set up by an older version.
|
|
19
|
+
- The README in English and Russian, with a reference of every command and flag ([README.ru.md](https://github.com/aleksei-shvets/estimetry/blob/main/README.ru.md)).
|
|
20
|
+
- Requires Node.js 22.12 or newer.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aleksei Shvets
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,417 @@
|
|
|
1
|
-
#
|
|
1
|
+
# estimetry
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** | [Русский](https://github.com/aleksei-shvets/estimetry/blob/main/README.ru.md)
|
|
4
|
+
|
|
5
|
+
Compares work estimates with the actual effort in AI-agent development and reuses that experience in the next estimate.
|
|
6
|
+
|
|
7
|
+
The CLI is `estimetry`, with the short alias `emt`.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
You need:
|
|
12
|
+
- Node.js 22.12 or newer;
|
|
13
|
+
- git;
|
|
14
|
+
- [Claude Code](https://docs.claude.com/en/docs/claude-code) — the only AI tool estimetry supports for now.
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm install -g estimetry
|
|
18
|
+
emt --version
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Install it globally: the hooks of Claude Code call `estimetry` from `PATH`.
|
|
22
|
+
|
|
23
|
+
To update later: `npm install -g estimetry@latest`, then `emt upgrade` once (see [After upgrading estimetry](#after-upgrading-estimetry)).
|
|
24
|
+
|
|
25
|
+
> estimetry is at 0.x: commands and the storage format may still change between minor versions. [CHANGELOG.md](CHANGELOG.md) says what changed and what to do after an upgrade.
|
|
26
|
+
|
|
27
|
+
## Getting started
|
|
28
|
+
|
|
29
|
+
1. In the root of a repository, run `estimetry init`. It sets up the Claude Code hooks and the `/emt-…` skills.
|
|
30
|
+
2. Start a new Claude Code session there and ask how long a task will take, or run `/emt-estimate`. The agent creates the task, estimates it by parts and saves the estimate once you approve it.
|
|
31
|
+
3. Run `/emt-start` and work as usual. The hooks measure the time of the agents and your own time; `emt status` shows it.
|
|
32
|
+
4. When the work is done, run `/emt-close`. The agent closes the task and asks you why the fact differs from the estimate.
|
|
33
|
+
|
|
34
|
+
Every closed task makes the next estimate more grounded: `emt similar` finds past tasks like the new one, and `emt calibrate` gives your own coefficient once there are enough of them.
|
|
35
|
+
|
|
36
|
+
## Help
|
|
37
|
+
|
|
38
|
+
`emt --help` lists every command, nested ones included (`task new`, `estimate save`, `parallel on`), grouped by stage: setup, tasks and estimates, measuring, closing. Each comes with its options; required ones are marked. Examples of the usual order close the list.
|
|
39
|
+
|
|
40
|
+
`emt <command> --help` or `emt help <command>` shows one command in full, e.g. `emt help task new`.
|
|
41
|
+
|
|
42
|
+
The same list with every flag is in the [command reference](#command-reference) at the end of this README.
|
|
43
|
+
|
|
44
|
+
## Setting up a project: `estimetry init`
|
|
45
|
+
|
|
46
|
+
Run it in the root of a repository:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
estimetry init
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
In a terminal it asks a few questions:
|
|
53
|
+
- which AI tools to set up (Claude Code for now);
|
|
54
|
+
- the development process (OpenSpec or none);
|
|
55
|
+
- how to share data with your team;
|
|
56
|
+
- whether to install a git hook.
|
|
57
|
+
|
|
58
|
+
`estimetry init --no-interactive` uses flags and defaults instead, and so does any run in CI or without a terminal. Running init again is safe: it updates what it installed and leaves everything else alone.
|
|
59
|
+
|
|
60
|
+
### What it installs
|
|
61
|
+
|
|
62
|
+
| What | Where | Who gets it |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| Hooks for 12 Claude Code events, each running `estimetry hook claude-code <event>` | `.claude/settings.local.json` | you |
|
|
65
|
+
| Skills `estimetry`, `emt-estimate`, `emt-start`, `emt-extra`, `emt-parallel`, `emt-manual`, `emt-close`, `emt-retro` (also the `/emt-…` commands) | `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`) | you, in every project |
|
|
66
|
+
| Project id and development process | `.estimetry/config.yaml` | the team; commit it so clones of the repository are one project |
|
|
67
|
+
|
|
68
|
+
With `--shared-hooks` the hooks go to `.claude/settings.json` and the skills to `.claude/skills/` of the project. A reminder to run `/emt-estimate` before naming a deadline is added to `CLAUDE.md`, between `<!-- estimetry:start -->` and `<!-- estimetry:end -->`. These are files the project commits, so the whole team gets them.
|
|
69
|
+
|
|
70
|
+
With `--track-commits` a `post-commit` hook is installed into the repository's hooks directory. This respects `core.hooksPath`, worktrees and husky (`.husky/post-commit`). An existing hook keeps its content: estimetry adds its own block between `# >>> estimetry >>>` and `# <<< estimetry <<<`. The hook runs estimetry in the background, so commits never wait for it. Colleagues without estimetry see nothing.
|
|
71
|
+
|
|
72
|
+
No task data ever goes into the repository. Tasks, estimates and the event journal live in `~/.local/share/estimetry/`, or in `ESTIMETRY_HOME` if set.
|
|
73
|
+
|
|
74
|
+
### Flags
|
|
75
|
+
|
|
76
|
+
| Flag | Meaning |
|
|
77
|
+
|---|---|
|
|
78
|
+
| `--tools <ids>` | AI tools, comma-separated: `claude-code` (alias `claude`) |
|
|
79
|
+
| `--flow <id>` | `openspec` or `none`; detected by default (`openspec/` in the root means OpenSpec) |
|
|
80
|
+
| `--share <mode>` | `none`, `calibration` or `cards`; only saved for now |
|
|
81
|
+
| `--track-commits` / `--no-track-commits` | install or remove the git hook |
|
|
82
|
+
| `--shared-hooks` / `--no-shared-hooks` | install for the whole team or for yourself only |
|
|
83
|
+
| `--force` | overwrite generated skills you have edited |
|
|
84
|
+
| `--no-interactive` | do not ask questions |
|
|
85
|
+
| `--json` | print the report as JSON |
|
|
86
|
+
|
|
87
|
+
A repeated run keeps what is installed: once the git hook or the shared install is in place, `estimetry init` without flags leaves it so. To undo it, run `estimetry init --no-track-commits` or `estimetry init --no-shared-hooks`.
|
|
88
|
+
|
|
89
|
+
### Good to know
|
|
90
|
+
|
|
91
|
+
- **Your edits to generated skills are kept.** Every generated skill carries `metadata.generatedBy` and a hash of its content. If you edit one, init keeps your version and reports it as `skipped`; `--force` overwrites it. A file of the same name that estimetry did not create is never touched.
|
|
92
|
+
- **A rewritten hook is yours.** estimetry recognises its hooks by the command prefix `estimetry hook claude-code`. If you change that command, init treats the hook as yours and adds its own next to it.
|
|
93
|
+
- **`settings.local.json` may not be ignored by git.** Claude Code adds `**/.claude/settings.local.json` to your global git excludes only when it writes that file itself. If init creates it and git does not ignore it, init offers to add the same line. With `--no-interactive` it only warns.
|
|
94
|
+
- **Hooks need `estimetry` on `PATH`.** When run through `npx`, the hooks will not find it, and init warns about that.
|
|
95
|
+
|
|
96
|
+
## Estimating a task
|
|
97
|
+
|
|
98
|
+
Ask the agent how long a task will take, or run `/emt-estimate`. Before it names any number, the agent:
|
|
99
|
+
1. agrees with you on the task type and the technologies the task really touches;
|
|
100
|
+
2. sketches the parts of the plan and runs `emt similar` — closed tasks like this one, with their estimates, fact, extra work and lessons;
|
|
101
|
+
3. runs `emt calibrate` — your coefficients and the one the estimate may apply;
|
|
102
|
+
4. shows the estimate by parts with what it rests on, and saves it with `emt estimate save` only after you approve it.
|
|
103
|
+
|
|
104
|
+
```sh
|
|
105
|
+
emt similar --type feature --stack typescript,node --hours 8
|
|
106
|
+
emt calibrate --type feature --stack typescript,node
|
|
107
|
+
emt calibrate --type feature --revise # for a revision of a task in progress
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- **Similarity** weighs the shared technologies (half), the type of the first estimate and, with `--hours`, the size. Each task shows what its similarity is made of. Without `--stack`, the stack of the project counts.
|
|
111
|
+
- **The coefficient** is the median of fact over estimate of the first slice with enough closed tasks: by type, then by technology. The overall slice mixes every kind of work and is shown for reference only. With fewer tasks than `calibration.minTasks` (5 by default) the estimate is **without calibration**, and the agent says so.
|
|
112
|
+
- **A calibrated estimate** multiplies all three numbers of every part by the coefficient and records it (`calibrated: true`, `calibration.coefficient`), so the next coefficient is computed from the estimate before it. A reserve goes only into the pessimistic hours: extra work you absorbed is already in the coefficient.
|
|
113
|
+
- **Nothing is written** by `emt similar` and `emt calibrate`; `calibration.json` is updated by closings and `emt rebuild`.
|
|
114
|
+
- **A changed email.** Calibration is personal, by `author.id` in `config.yaml`. List earlier ids so that their cards stay yours:
|
|
115
|
+
|
|
116
|
+
```yaml
|
|
117
|
+
author:
|
|
118
|
+
id: new@example.com
|
|
119
|
+
aliases: [old@example.com]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Measuring a task
|
|
123
|
+
|
|
124
|
+
Once a task is started (`emt start`), the Claude Code hooks record its sessions into the task's journal. `emt status` shows the fact measured so far: the time of the agents, your own time, and how certain the numbers are.
|
|
125
|
+
|
|
126
|
+
### What counts
|
|
127
|
+
|
|
128
|
+
- **Agent time** — while the main agent works on a turn or a subagent runs, including tools that take a while.
|
|
129
|
+
- **Your time** — while the session is yours: reviewing results and writing the next prompt. Pauses longer than the idle threshold do not count.
|
|
130
|
+
- **Not counted** — commands left running in the background after the agent finished its turn (`run_in_background`, or a subagent waiting for its own background job). The machine works then, not the agent.
|
|
131
|
+
|
|
132
|
+
### How certain the fact is
|
|
133
|
+
|
|
134
|
+
Some stretches are decided by a rule, not by an event: a silence of 20 minutes after the agent answered may be you reviewing the result, or you away. `emt status` shows the range the fact lies in:
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
fact 29h 43m of 58h 30m (51%)
|
|
138
|
+
uncertainty 27h 53m – 34h 0m (21% of the fact, above the 5% target)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- **The lower bound** leaves out the doubtful stretches the rules counted: silences between half the threshold and the threshold, tools that ran longer than twice the threshold, the start of a turn a session joined midway.
|
|
142
|
+
- **The upper bound** adds the doubtful stretches the rules left out: pauses up to twice the threshold, the tail of a turn or subagent that never reported its end, long waits that ended without a duration.
|
|
143
|
+
|
|
144
|
+
Estimates and calibration compare with the fact itself; the range only tells how far it could move. Most of it is usually your own silences after a finished turn: nothing records whether you worked then, so it stays open.
|
|
145
|
+
|
|
146
|
+
### Session logs, tokens and cost
|
|
147
|
+
|
|
148
|
+
Claude Code keeps a log of every session. estimetry reads it when a session ends (also on `/clear` and `/resume`) and before a task closes, and keeps in the task's journal only what it needs:
|
|
149
|
+
- when the agent's turns and subagents began and ended: a turn whose end the hooks missed ends where the log ends it, and a session that joined midway starts its turn where the log starts it;
|
|
150
|
+
- tokens by model, with their times, and the session's total cost.
|
|
151
|
+
|
|
152
|
+
The texts of the log — prompts, answers, tool inputs and outputs, descriptions and types of subagents — are never read into the journal.
|
|
153
|
+
|
|
154
|
+
`emt status` and the card show the tokens of the task and its cost, with how many of its sessions had a log. When only part of a session's tokens belongs to the task (the session began before `emt start`, or served another task too), the task gets the matching share of the session's cost, weighing each kind of token by its price relative to an input token, and the cost is marked approximate.
|
|
155
|
+
|
|
156
|
+
The cost is the total Claude Code itself records in the session log, at API prices. On a subscription it is not what you pay: read it as a measure for comparing tasks with each other, not as spending.
|
|
157
|
+
|
|
158
|
+
Sessions that ended before you installed this version are read when the task closes. Claude Code deletes logs after 30 days; for longer tasks raise `cleanupPeriodDays` in its settings.
|
|
159
|
+
|
|
160
|
+
### Which task a session serves
|
|
161
|
+
|
|
162
|
+
- **One task in progress** — a session binds to it by itself.
|
|
163
|
+
- **Several tasks in progress** — the agent gets the session id at the start of the session and asks you which task it is. It then runs `emt attach <task> --session <id>`. For the first task of the session, its work since the task started counts, as when the session binds by itself. The same command switches a running session to another task; the time before and after the switch goes to the right task.
|
|
164
|
+
- **No task in progress** — the session's time is kept in a journal of the project and counts for no task. Start a task, even with `emt start --at "<when you began>"`, and the session's work since then moves into it.
|
|
165
|
+
|
|
166
|
+
### Restarts and parallel sessions
|
|
167
|
+
|
|
168
|
+
The hooks find the project by the directory Claude Code runs in, not by the session id.
|
|
169
|
+
|
|
170
|
+
- **After a restart** (VS Code, a crash, a reboot) the new session has a new id and binds again by the rules above: with one task in progress, time goes on into it without anything to do. With several, answer the agent which task it is: once attached, the work the new session did since the task started counts too.
|
|
171
|
+
- **A turn cut off by a crash** gets no end. Its tail is closed by the idle threshold and shows as uncertainty (`± …` in `emt status`). The time between the crash and the restart does not count.
|
|
172
|
+
- **Two sessions on one task** both write into its journal. Overlapping agent time counts once, so the fact is shorter than the work of both agents together. Switch on parallel mode (`emt parallel on --agents 2`): calibration then uses the sequential equivalent, the sum of the agents' work.
|
|
173
|
+
- **Two sessions on two tasks** each serve their own task after `emt attach`. A commit goes to the task of the session active last: the git hook does not know which session made it. When both commit at the same moment, one commit may land in the other task. This affects only the code volume of the card, not the time.
|
|
174
|
+
|
|
175
|
+
### Code in another working copy or repository
|
|
176
|
+
|
|
177
|
+
The agent may run in one repository, where the OpenSpec artifacts are, and write code elsewhere.
|
|
178
|
+
|
|
179
|
+
- **Time and plan progress** are not affected: time goes to the task of the session, and the plan is read where the artifacts are.
|
|
180
|
+
- **A git worktree** of a registered working copy belongs to its project, with or without a committed `.estimetry/config.yaml`: a task started in the worktree is a task of that project, and a session opened in the main working copy sees it. Another clone without the config is a project of its own.
|
|
181
|
+
- **The plan of a task kept in a worktree** is read in the working copy that holds its changes (the groups of its estimate and of every revision of it) — where they moved last when copies differ — even when the session runs in the main working copy: the percent done, the completion of a change, checkpoints and the code volume at closing. A worktree without its own `.estimetry/config.yaml` takes the flow of the other working copies of the project.
|
|
182
|
+
- **Commits in a worktree** are recorded into the task: worktrees share the git hooks of the repository (with `init --track-commits`). The code volume is measured at closing in the working copy of the task, wherever `emt close` runs: the commits reachable from its `HEAD` and its uncommitted changes. Uncommitted changes of other worktrees are not seen.
|
|
183
|
+
- **Another repository** belongs to the task only when you add it: run `estimetry init --track-commits` and `emt attach <task>` in it. Then its commits are recorded and its code is measured at closing.
|
|
184
|
+
|
|
185
|
+
The code volume is a self-check only: it never changes the fact or the coefficients.
|
|
186
|
+
|
|
187
|
+
### Checkpoints
|
|
188
|
+
|
|
189
|
+
Every 20 minutes of work a checkpoint records the state of the plan (the checkboxes of OpenSpec `tasks.md`), `HEAD` and the uncommitted changes, all of the working copy of the task. It runs only in background hooks. Set the interval in `~/.local/share/estimetry/config.yaml`:
|
|
190
|
+
|
|
191
|
+
```yaml
|
|
192
|
+
measurement:
|
|
193
|
+
checkpointMinutes: 20 # 10 to 30
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
After a checkpoint, the agent is reminded with your next prompt to record work outside the plan with `/emt-extra`.
|
|
197
|
+
|
|
198
|
+
### Plan progress
|
|
199
|
+
|
|
200
|
+
`emt status` also shows how much of the plan is done:
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
plan 51% done by changes (58h 30m of 58h 30m in groups)
|
|
204
|
+
not started close-retro-cards, estimate-mode
|
|
205
|
+
changes 4 done, last hooks-and-flows 2026-11-01 (approx.)
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- **Parts are linked by `group`.** A part of the estimate whose `group` is the name of an OpenSpec change is linked to that change, in any project of the task. An archived change counts as 100% done, an active one by its checked boxes, a change not created yet as 0%. The percent is weighted by the most likely hours of the linked parts.
|
|
209
|
+
- **The plan of a task** is its active changes plus the archived ones dated no earlier than the day before the task started. An older archive with the same name belongs to earlier work.
|
|
210
|
+
- **Groups without a change** are listed as `not started`, as `possible typo` when a change has a similar name, or as `archived before start`.
|
|
211
|
+
- **Without groups** (or without an estimate) the plan is counted by the checkboxes of all its changes and marked as not linked to the estimate.
|
|
212
|
+
- **Not tracked** when the project's flow is `none` or unknown, the project has no `.estimetry/config.yaml`, or it is not on this machine. For a task in several projects, the percent counts the projects estimetry can read and lists the others under `not tracked`: their groups may look not started although they are done.
|
|
213
|
+
- **Several working copies** of a project (worktrees, clones): the plan is read in the working copy of the task, the one that holds its changes (see [Code in another working copy or repository](#code-in-another-working-copy-or-repository)); without such a copy, in the one you work in.
|
|
214
|
+
|
|
215
|
+
A change is completed when its directory appears in the archive, however it got there: `openspec archive`, a skill moving it, or you in a terminal. The next hook call of a session bound to the task records it, with the time of the move. Changes already archived when estimetry first looks at a task are recorded with their date only, marked `(approx.)`. A change moved back out of the archive no longer counts as completed. The start of a session shows the percent too (`plan 51% done`), and `emt parallel on` records it.
|
|
216
|
+
|
|
217
|
+
## Revising the estimate
|
|
218
|
+
|
|
219
|
+
Once a task is started, its estimate is the plan the fact is compared with, and `emt estimate save` refuses to change it. When the plan turns out wrong but the scope and deadline stay — a design error, something the analysis missed — revise it:
|
|
220
|
+
|
|
221
|
+
```sh
|
|
222
|
+
emt estimate revise plan2.yaml --reason "design was wrong" --category missed-analysis --spent exclude --lost-from "2026-11-02 10:00"
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`emt task show <task>` gives the parts of the estimate in force (with `--json`, in the format of an estimate file): start the new one from them.
|
|
226
|
+
|
|
227
|
+
- `--spent include` — the work so far counts toward the new estimate.
|
|
228
|
+
- `--spent exclude` — the work since `--lost-from` (by default since the start or the previous revision) up to the revision (`--at`, by default now) was thrown away. It is not deleted: `emt status` shows it apart as lost and compares only the counted fact with the new estimate.
|
|
229
|
+
- `--covers <id>` — extra work already recorded for the same loss, so the loss is not counted twice. Only with `--spent exclude`, and an extra work can be covered by one revision only. The command lists the extra work recorded in the window, with ids, so you can name it.
|
|
230
|
+
- Archived changes of the thrown-away work leave the plan: they give no percent, no completion and no proposal to close. A change archived again later counts as usual.
|
|
231
|
+
|
|
232
|
+
The first estimate stays in the journal and in the card: calibration compares the whole fact with it, so a late revision cannot make an estimate look right. The revised estimate is measured too, against the counted fact (see [Calibration](#calibration)). If the customer agreed to more scope or time, use `emt renegotiate` instead.
|
|
233
|
+
|
|
234
|
+
## Closing a task
|
|
235
|
+
|
|
236
|
+
A task closes only when you agree. When a change of the task moves into the archive, the agent gets a note on your next prompt and asks whether it was the last one and whether to close the task. It never closes the task by itself.
|
|
237
|
+
|
|
238
|
+
```sh
|
|
239
|
+
emt close # shows the fact and the plan, then asks
|
|
240
|
+
emt close --yes # without a terminal (an agent): only after you agreed
|
|
241
|
+
emt close --at "2026-11-02 18:00" # the work ended earlier
|
|
242
|
+
emt close --abandoned # the task was dropped; it is not used for calibration
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Closing records the code volume and the plan, ends parallel mode, and lets the sessions of the task go: a session that closed a task does not move to another task by itself until it starts again or you run `emt attach <task> --session <id>`.
|
|
246
|
+
|
|
247
|
+
Then hold the retro with the agent (`/emt-retro`): why the fact differs from the estimate and one lesson for next time.
|
|
248
|
+
|
|
249
|
+
```sh
|
|
250
|
+
emt retro --reason "manual-testing: two devices instead of one" --reason "API docs were outdated" --lesson "plan manual testing per platform"
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
A reason that starts with the id of an estimate part (`manual-testing:`) is about that part. Running `emt retro` again replaces the retro.
|
|
254
|
+
|
|
255
|
+
- **More work agreed with the customer.** `emt renegotiate "Payments v2" --description "refunds added"` closes the task as it is and creates a new task for the rest, linked to it. Estimate and start the new task as usual.
|
|
256
|
+
- **Closed by mistake.** `emt reopen T-3` opens the task again; its card goes away until the next closing.
|
|
257
|
+
- **Manual time of a part.** `emt manual 40m "testing on device" --part manual-testing` counts the time toward that part of the estimate.
|
|
258
|
+
- **Closed tasks** are listed with `emt task list --closed`; `emt task show T-3` shows the card.
|
|
259
|
+
|
|
260
|
+
### The card
|
|
261
|
+
|
|
262
|
+
Every closed task gets a card in `~/.local/share/estimetry/cards/<task>.yaml`, about 50 lines. It holds:
|
|
263
|
+
- the estimate and the fact, also by parts of the estimate;
|
|
264
|
+
- extra work and parallel mode;
|
|
265
|
+
- the code volume, as lines of production code, tests, config and docs;
|
|
266
|
+
- the retro.
|
|
267
|
+
|
|
268
|
+
Time is split between parts by the checkboxes their changes closed between checkpoints. Time no part can claim is shown as `unattributed`.
|
|
269
|
+
|
|
270
|
+
A revised task keeps both estimates: `estimate` and `parts` are the first estimate, `currentEstimate` and `currentParts` the one in force at the closing. The card also lists every revision with the work its window lost and how much was counted when it was made, and gives the counted fact next to the whole one. Time is split between the parts of the current estimate from the moment of the last revision; what was counted before it is shown as `before revision`. Extra work named in `--covers` is listed apart, as covered by the revision.
|
|
271
|
+
|
|
272
|
+
The code volume counts the task's recorded commits still reachable from `HEAD`, plus what is not committed. Without recorded commits it counts your commits since the task started. Generated files (lock files, `*.g.dart`, `dist/` and the like) are left out. Lines are only a self-check: they never change the fact or the coefficients.
|
|
273
|
+
|
|
274
|
+
Names, descriptions and the retro sit in a separate `text` section of the card, apart from the numbers.
|
|
275
|
+
|
|
276
|
+
### Calibration
|
|
277
|
+
|
|
278
|
+
`calibration.json` holds your coefficients, computed from your cards:
|
|
279
|
+
- fact over estimate, overall, by task type and by technology (median, mean, number of tasks);
|
|
280
|
+
- the share of extra work by category, and how much scope renegotiations added;
|
|
281
|
+
- how well the code volume was forecast;
|
|
282
|
+
- which kinds of parts run over.
|
|
283
|
+
|
|
284
|
+
A coefficient based on fewer than 5 tasks is shown but not applied. Set the minimum in `config.yaml`:
|
|
285
|
+
|
|
286
|
+
```yaml
|
|
287
|
+
calibration:
|
|
288
|
+
minTasks: 5
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Tasks in parallel mode count with their sequential equivalent. Abandoned tasks and tasks with manual time only are left out.
|
|
292
|
+
|
|
293
|
+
Revised tasks give two accuracies:
|
|
294
|
+
- the main coefficient compares the whole fact with the **first** estimate, by the type of that estimate: that is the number the PM got;
|
|
295
|
+
- `revised` compares the counted fact with the **current** estimate: how good the estimate made at the revision was, and how far into the work revisions usually come;
|
|
296
|
+
- `revisions` shows, by task type, category and `--spent`, how much revisions grow the estimate and how much work they throw away.
|
|
297
|
+
|
|
298
|
+
The parts of a revised task count only if no more than 5% of its counted fact was spent before the revision. Tasks with `--spent exclude` stay out of the code volume and lines per hour: rolled back lines say nothing about the size of the task.
|
|
299
|
+
|
|
300
|
+
`emt rebuild` rebuilds task snapshots, cards and `calibration.json` from the journals, for example after an upgrade changed a formula.
|
|
301
|
+
|
|
302
|
+
### What is never stored
|
|
303
|
+
|
|
304
|
+
The journal keeps when things happened, not what was said or done: no prompt texts, no tool inputs or outputs, no commands, no commit messages. Commits are recorded as their hash, parents, `patch-id` and lines per file. From session logs it keeps times, token counts by model and the cost; a log that cannot be read leaves only a code in `errors.log`.
|
|
305
|
+
|
|
306
|
+
### After upgrading estimetry
|
|
307
|
+
|
|
308
|
+
Run `emt upgrade` once, from any directory. It sets estimetry up again in every working copy of every registered project on this machine (worktrees included), each with the choices it already has: tools, flow, a personal or shared install, the commit hook. It shows what will change and asks first; without a terminal it needs `--yes`. A copy where estimetry was never set up is skipped, and so is one that is not on this machine. With a shared install the plan warns that the files it changes are committed by the project. To update a single project instead, run `emt init` inside it.
|
|
309
|
+
|
|
310
|
+
Until then the hooks keep working: they run the new `estimetry` from `PATH`; only what `init` wrote is old — the hook settings in each project, the skills and, with a shared install, the reminder in `CLAUDE.md`. At the start of a session in a project set up by an older version, the agent is told to suggest `emt upgrade`; it never runs it on its own.
|
|
311
|
+
|
|
312
|
+
Update every installed copy of estimetry at once. Cards written by an older version are rebuilt from the journals on the next closing, `emt task show` or `emt rebuild`. A newer card stops an older estimetry from rewriting `calibration.json` and is reported instead; versions before this check skip such cards silently, so close no task with them.
|
|
313
|
+
|
|
314
|
+
## Command reference
|
|
315
|
+
|
|
316
|
+
Every command and flag, by stage, as `emt --help` lists them. `estimetry` and `emt` are the same command.
|
|
317
|
+
|
|
318
|
+
<!-- commands:start: generated from the CLI by `npm run docs:commands` -->
|
|
319
|
+
|
|
320
|
+
### Setup
|
|
321
|
+
|
|
322
|
+
- **`emt init`** — set up estimetry in this project: hooks, skills and commands of the AI tool, project config
|
|
323
|
+
- `--tools <ids>` — AI tools, comma-separated (claude-code)
|
|
324
|
+
- `--flow <id>` — development process: openspec or none (default: detected)
|
|
325
|
+
- `--share <mode>` — sharing with the team: none, calibration, cards
|
|
326
|
+
- `--track-commits` — install a git post-commit hook
|
|
327
|
+
- `--no-track-commits` — remove the git post-commit hook
|
|
328
|
+
- `--shared-hooks` — install for the whole team, into files the project commits
|
|
329
|
+
- `--no-shared-hooks` — install for yourself only (default)
|
|
330
|
+
- `--force` — overwrite generated skills you have edited
|
|
331
|
+
- `--no-interactive` — do not ask; use flags and defaults
|
|
332
|
+
- **`emt upgrade`** — after updating estimetry: set it up again in every project on this machine, each with its own choices
|
|
333
|
+
- `--yes` — the user has already agreed (needed without a terminal)
|
|
334
|
+
- **`emt rebuild [task]`** — rebuild task snapshots, cards and calibration.json from the journals
|
|
335
|
+
|
|
336
|
+
### Tasks and estimates
|
|
337
|
+
|
|
338
|
+
- **`emt task new <title>`** — create a task in the current project
|
|
339
|
+
- `--type <type>` — task type: feature, integration, bugfix, refactor, infra, migration, research
|
|
340
|
+
- `--ticket <key>` — key of the ticket in an external tracker
|
|
341
|
+
- **`emt task list`** — list tasks of the current project
|
|
342
|
+
- `--all` — list tasks of all projects
|
|
343
|
+
- `--closed` — include closed tasks
|
|
344
|
+
- **`emt task show <task>`** — show a task
|
|
345
|
+
- **`emt similar`** — find closed tasks like a new one: their estimates, fact, extra work and lessons
|
|
346
|
+
- `--type <type>` — task type of the new task
|
|
347
|
+
- `--stack <labels>` — comma-separated technologies the task touches; defaults to the stack of the project
|
|
348
|
+
- `--hours <hours>` — preliminary most likely hours of the new task, before calibration
|
|
349
|
+
- `--limit <n>` — how many tasks to show (default: "5")
|
|
350
|
+
- **`emt calibrate`** — show your coefficients for a type and a stack, and the one an estimate may apply
|
|
351
|
+
- `--type <type>` — task type of the task being estimated
|
|
352
|
+
- `--stack <labels>` — comma-separated technologies the task touches; defaults to the stack of the project
|
|
353
|
+
- `--revise` — for a revision of a task in progress: the coefficient of estimates made during work
|
|
354
|
+
- **`emt estimate save <file>`** — make an estimate file the plan of a task (allowed until work starts)
|
|
355
|
+
- `--task <id>` — task id; defaults to the only new or estimated task of this project
|
|
356
|
+
- **`emt estimate revise [file]`** — revise the plan of a task in progress: the old estimate stays, the new one is compared with the counted fact
|
|
357
|
+
- `--reason <text>` — why the plan changed: a short summary agreed with the user
|
|
358
|
+
- `--category <category>` — new-requirement, missed-analysis, rework or environment
|
|
359
|
+
- `--spent <policy>` — include: work so far counts; exclude: work in the lost window was thrown away
|
|
360
|
+
- `--lost-from <time>` — with exclude: when the work started going the wrong way (ISO 8601 or "YYYY-MM-DD HH:MM")
|
|
361
|
+
- `--covers <id>` — id of extra work that describes the same loss; repeat for several
|
|
362
|
+
- `--at <time>` — when the new estimate starts to hold; defaults to now
|
|
363
|
+
- `--task <id>` — task id; defaults to the only task in progress in this project
|
|
364
|
+
- `--repair` — write the missing plan snapshot of the last revision
|
|
365
|
+
|
|
366
|
+
### Measuring
|
|
367
|
+
|
|
368
|
+
- **`emt start [task]`** — start work on a task; from now on its effort is recorded
|
|
369
|
+
- `--at <time>` — backdate the start (ISO 8601 or "YYYY-MM-DD HH:MM"), for work begun earlier
|
|
370
|
+
- **`emt attach <task>`** — connect a task to the current project (for tasks that span several repositories)
|
|
371
|
+
- `--session <id>` — also bind this session of the AI tool to the task (when several tasks are in progress)
|
|
372
|
+
- **`emt manual <duration> <description>`** — record time the hooks did not see: your work outside agent sessions, or agent work with --agent
|
|
373
|
+
- `--at <time>` — when the work ended (ISO 8601 or "YYYY-MM-DD HH:MM"); merges with measured time
|
|
374
|
+
- `--agent` — agent time, e.g. work done before estimetry was installed
|
|
375
|
+
- `--task <id>` — task id; defaults to the only task in progress in this project
|
|
376
|
+
- `--part <id>` — id of the estimate part the time belongs to, e.g. manual-testing
|
|
377
|
+
- **`emt extra <description>`** — record work outside the estimated plan
|
|
378
|
+
- `--category <category>` — one of: new-requirement, missed-analysis, rework, environment (required)
|
|
379
|
+
- `--time <duration>` — your guess of what it cost; does not change the fact
|
|
380
|
+
- `--lines <n>` — lines of code it took
|
|
381
|
+
- `--change <name>` — change it belongs to
|
|
382
|
+
- `--task <id>` — task id; defaults to the only task in progress in this project
|
|
383
|
+
- **`emt parallel on`** — switch parallel mode on; records how much of the budget is spent
|
|
384
|
+
- `--reason <text>` — why the work goes parallel
|
|
385
|
+
- `--agents <n>` — number of agents
|
|
386
|
+
- `--parts <ids>` — comma-separated ids of the estimate parts done in parallel
|
|
387
|
+
- `--task <id>` — task id; defaults to the only task in progress in this project
|
|
388
|
+
- **`emt parallel off`** — switch parallel mode off
|
|
389
|
+
- `--task <id>` — task id; defaults to the only task in progress in this project
|
|
390
|
+
- **`emt status [task]`** — show the fact of a task so far: agents, you, uncertainty, and the estimate
|
|
391
|
+
- `--json` — print JSON (durations in minutes)
|
|
392
|
+
|
|
393
|
+
### Closing
|
|
394
|
+
|
|
395
|
+
- **`emt close [task]`** — close a task after the user agreed; then run `emt retro`
|
|
396
|
+
- `--at <time>` — when the work ended (ISO 8601 or "YYYY-MM-DD HH:MM"); defaults to now
|
|
397
|
+
- `--abandoned` — the task was dropped: it is not used for calibration
|
|
398
|
+
- `--yes` — the user has already agreed to close it (needed without a terminal)
|
|
399
|
+
- **`emt reopen <task>`** — open a task closed by mistake
|
|
400
|
+
- **`emt retro [task]`** — record why the fact differs from the estimate, and one lesson
|
|
401
|
+
- `--reason <text>` — a reason, optionally "<part id>: <text>"; repeat for several (required)
|
|
402
|
+
- `--lesson <text>` — one lesson for the next estimate (required)
|
|
403
|
+
- **`emt renegotiate <title>`** — the customer agreed to more work: close the task as it is and start a new one for the rest
|
|
404
|
+
- `--task <id>` — the task being renegotiated; defaults to the only task in progress in this project
|
|
405
|
+
- `--description <text>` — what changed; defaults to the title
|
|
406
|
+
- `--category <category>` — category of the extra work, new-requirement by default
|
|
407
|
+
- `--type <type>` — type of the new task; defaults to the type of the original
|
|
408
|
+
- `--at <time>` — when the original work ended; defaults to now
|
|
409
|
+
- `--yes` — the user has already agreed (needed without a terminal)
|
|
410
|
+
|
|
411
|
+
### General options
|
|
412
|
+
|
|
413
|
+
- `-v, --version` — output the version number
|
|
414
|
+
- `-h, --help` — display help for command
|
|
415
|
+
- `--json` — print JSON; most commands have it
|
|
416
|
+
|
|
417
|
+
<!-- commands:end -->
|