@notchlet/cli 0.0.0-stage → 0.2.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/dist/auth.js +380 -0
- package/dist/cli-format.js +46 -0
- package/dist/cli-prompt.js +73 -0
- package/dist/cli.js +1040 -0
- package/dist/guidance-install.js +111 -0
- package/dist/integration.js +806 -0
- package/dist/setup.js +92 -0
- package/guidance/aliases.json +27 -0
- package/guidance/generated/claude-code/notchlet-deliver/SKILL.md +94 -0
- package/guidance/generated/claude-code/notchlet-implement/SKILL.md +94 -0
- package/guidance/generated/claude-code/notchlet-init/SKILL.md +30 -0
- package/guidance/generated/claude-code/notchlet-mcp/SKILL.md +60 -0
- package/guidance/generated/claude-code/notchlet-plan/SKILL.md +100 -0
- package/guidance/generated/claude-code/notchlet-platform/SKILL.md +85 -0
- package/guidance/generated/claude-code/notchlet-review/SKILL.md +68 -0
- package/guidance/generated/claude-code/notchlet-super/SKILL.md +47 -0
- package/guidance/generated/compatibility.json +94 -0
- package/guidance/generated/manifest.json +140 -0
- package/guidance/generated/opencode/notchlet-deliver/SKILL.md +94 -0
- package/guidance/generated/opencode/notchlet-implement/SKILL.md +94 -0
- package/guidance/generated/opencode/notchlet-init/SKILL.md +30 -0
- package/guidance/generated/opencode/notchlet-mcp/SKILL.md +60 -0
- package/guidance/generated/opencode/notchlet-plan/SKILL.md +100 -0
- package/guidance/generated/opencode/notchlet-platform/SKILL.md +85 -0
- package/guidance/generated/opencode/notchlet-review/SKILL.md +68 -0
- package/guidance/generated/opencode/notchlet-super/SKILL.md +47 -0
- package/package.json +1 -6
- package/scripts/generate-guidance.mjs +115 -0
- package/README.md +0 -3
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: notchlet-plan
|
|
3
|
+
description: Use when creating or refining Notchlet epics, stories, and tasks from product documents, tickets, or existing workflows, with acceptance criteria, dependencies, estimates, and verified hierarchy. Produces a definition of ready before implementation begins.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Plan executable Notchlet backlogs
|
|
7
|
+
|
|
8
|
+
Native `backlog_development_context`, `backlog_comments_list`, `backlog_comment_add`, and `backlog_activities_list` are available on the connected `notchlet_*` host; discover live tool names and schemas and use targeted-read/comment fallbacks where needed. Context is bounded to 32 KiB serialized bytes, may include truncation metadata and scoped cursors, and should be expanded only as needed.
|
|
9
|
+
|
|
10
|
+
## Entry criteria
|
|
11
|
+
|
|
12
|
+
- Product is resolved via `notchlet_workspace_context` or `notchlet_workspace_search`.
|
|
13
|
+
- Source documents (BRD/PRD/SRD/CUSTOM) or linked tickets are available and read.
|
|
14
|
+
- You know what outcome is requested; if not, ask before planning.
|
|
15
|
+
|
|
16
|
+
## Discover scope
|
|
17
|
+
|
|
18
|
+
1. Resolve the product from live workspace context. Read existing backlog/search results to avoid duplicates. Prefer refining an existing item when it covers the same requested work.
|
|
19
|
+
2. Read relevant BRD/PRD/SRD or CUSTOM documents and linked tickets. For migrations, inspect actual source workflows and code callers before claiming detailed coverage.
|
|
20
|
+
3. Identify deliverables, exclusions, dependencies, and acceptance criteria. Never substitute generic migration titles for inspected behavior.
|
|
21
|
+
4. Before decomposing an epic or story, inspect its current children, reuse/update matching existing children, and create only missing work. Do not duplicate already represented tasks.
|
|
22
|
+
|
|
23
|
+
## Risks and blockers
|
|
24
|
+
|
|
25
|
+
- Identify upstream dependencies (other items, teams, or external services) that must complete first.
|
|
26
|
+
- Flag items that cannot start until a dependent item reaches `DONE`.
|
|
27
|
+
- Mark items with uncertain requirements as needing clarification before implementation.
|
|
28
|
+
|
|
29
|
+
## Decompose proportionately
|
|
30
|
+
|
|
31
|
+
- **Epic:** outcome and measurable completion conditions across the initiative.
|
|
32
|
+
- **Story:** a coherent user/system capability that can be verified independently. Include acceptance criteria and dependency titles/IDs.
|
|
33
|
+
- **Task:** actionable implementation or verification work with concrete scope, expected artifacts, and a check demonstrating completion.
|
|
34
|
+
- Keep planning lightweight. For a small code change, use the existing item description with a concise outcome and acceptance checks; do not require OpenSpec artifacts, create a proposal/design/spec-document hierarchy, or introduce a new spec/change-management system. Hosted OpenCode is not a prerequisite.
|
|
35
|
+
- Keep an evolving short approach in the description or a comment. Do not replace user-authored requirements with progress logs.
|
|
36
|
+
- Avoid overlapping tasks that implement the same runtime/provider/configuration behavior twice. Include frontend/caller changes, data implications, and release work when required by the source behavior.
|
|
37
|
+
- Estimate only when useful. Label estimates provisional. Treat story estimates and task estimates as alternative rollups; never add both into one total.
|
|
38
|
+
- Do not infer assignments, due dates, or urgency without requirements.
|
|
39
|
+
|
|
40
|
+
## Definition of ready (before implementation)
|
|
41
|
+
|
|
42
|
+
A story or task is ready for `notchlet-implement` only when:
|
|
43
|
+
|
|
44
|
+
- [ ] Acceptance criteria are written and measurable (given/when/then or equivalent).
|
|
45
|
+
- [ ] Dependencies are listed with existing item titles and numeric IDs, or marked "none".
|
|
46
|
+
- [ ] Scope is specific: capability, route, or component is named.
|
|
47
|
+
- [ ] Verification criteria are defined (what test or evidence proves completion).
|
|
48
|
+
- [ ] No unresolved blocking dependency remains.
|
|
49
|
+
|
|
50
|
+
Description template:
|
|
51
|
+
|
|
52
|
+
```markdown
|
|
53
|
+
## Outcome
|
|
54
|
+
<observable result and source requirement>
|
|
55
|
+
|
|
56
|
+
## Scope
|
|
57
|
+
- <specific capability, route, or component>
|
|
58
|
+
|
|
59
|
+
## Acceptance criteria
|
|
60
|
+
- <given/when/then or measurable check>
|
|
61
|
+
|
|
62
|
+
## Dependencies
|
|
63
|
+
- <existing item title and numeric ID, or none>
|
|
64
|
+
|
|
65
|
+
## Verification
|
|
66
|
+
- <test/evidence required>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Persist and verify
|
|
70
|
+
|
|
71
|
+
1. Create the epic, then stories, then tasks **sequentially**, capturing each returned numeric ID for `parentId`. Do not guess key sequences or rely on display keys being unique.
|
|
72
|
+
2. Check for successful writes before retrying errors. Keep track of partial creation so retries do not duplicate items.
|
|
73
|
+
3. Read the root item after creation and verify child counts, types, product, parent links, descriptions, and estimates. If the hierarchy is truncated, fetch children individually.
|
|
74
|
+
4. Report verified totals and a compact hierarchy. Report service anomalies explicitly; do not claim keys/parents were repaired using unsupported operations.
|
|
75
|
+
|
|
76
|
+
For existing work, fetch the latest description before editing and preserve its requirements, evidence, and user-authored content. Pass `expectedDescriptionRevision` on description updates when the live schema supports it; reread and reconcile conflicts. Prefer explicit create operations over batch generation unless the batch payload contract is established.
|
|
77
|
+
|
|
78
|
+
## Exit criteria
|
|
79
|
+
|
|
80
|
+
- All planned items have a definition of ready met.
|
|
81
|
+
- Hierarchy (epic → stories → tasks) is verified in Notchlet.
|
|
82
|
+
- Items are in the correct status (typically `TODO` or `IN_PROGRESS` for the first executable item).
|
|
83
|
+
|
|
84
|
+
## When NOT to use
|
|
85
|
+
|
|
86
|
+
- When you only need to implement an already-planned item — use `notchlet-implement` instead.
|
|
87
|
+
- When you only need to review or deliver completed work — use `notchlet-review` or `notchlet-deliver` instead.
|
|
88
|
+
- When you need to set up the MCP connection first — use `notchlet-mcp` instead.
|
|
89
|
+
|
|
90
|
+
## Related skills
|
|
91
|
+
|
|
92
|
+
- `notchlet-platform` — resolve the product and backlog item before planning
|
|
93
|
+
- `notchlet-implement` — implement tasks after planning establishes Definition of Ready
|
|
94
|
+
- `notchlet-super` — orchestrates the full cycle including planning
|
|
95
|
+
|
|
96
|
+
## When to use
|
|
97
|
+
|
|
98
|
+
- Creating or refining epics, stories, and tasks.
|
|
99
|
+
- Before implementation begins, to establish a definition of ready.
|
|
100
|
+
- When scope, dependencies, or acceptance criteria need clarification.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: notchlet-platform
|
|
3
|
+
description: Use when discovering the Notchlet platform, resolving products and backlog items, or understanding available MCP operations and limitations before planning, implementing, or delivering work.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Notchlet Platform Discovery
|
|
7
|
+
|
|
8
|
+
Use this skill first to understand what is available on the connected Notchlet platform before planning, implementing, or delivering work.
|
|
9
|
+
|
|
10
|
+
## Discover the platform
|
|
11
|
+
|
|
12
|
+
1. Read available MCP operations and limitations from the connected `notchlet_*` host. Discover live tool names and schemas; never fabricate tool calls.
|
|
13
|
+
2. Use `notchlet_workspace_context` to list accessible organizations, teams, and products.
|
|
14
|
+
3. Use `notchlet_workspace_search` to search products, documents, backlog items, and tickets by query.
|
|
15
|
+
4. Resolve a product by ID or name before creating or refining backlog items under it.
|
|
16
|
+
|
|
17
|
+
## Resolve backlog items
|
|
18
|
+
|
|
19
|
+
1. Resolve a backlog item by numeric ID, or search its title/key and fetch it with `notchlet_backlog_get`.
|
|
20
|
+
2. If keys are duplicated, distinguish by title, product, parent, and numeric ID. Ask only if still ambiguous.
|
|
21
|
+
3. Read the item's description, acceptance criteria, children, assignments, and linked documents before acting.
|
|
22
|
+
4. Use `backlog_development_context` (`itemId`; optional `section`, `cursor`, `knownFingerprint`, `limit`) for bounded item/ancestor/child/comment/document/repository/Git context. Its response is capped at 32 KiB serialized bytes and may include truncation metadata and scoped cursors; expand only what is needed, follow cursors with the same limit, and do not assume a truncated page is complete.
|
|
23
|
+
|
|
24
|
+
### Example MCP tool invocations
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
// Resolve workspace context to find products
|
|
28
|
+
{
|
|
29
|
+
"tool": "notchlet_workspace_context"
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
// Fetch a backlog item by ID
|
|
33
|
+
{
|
|
34
|
+
"tool": "notchlet_backlog_get",
|
|
35
|
+
"arguments": { "id": 42 }
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Get bounded development context for an item
|
|
39
|
+
{
|
|
40
|
+
"tool": "backlog_development_context",
|
|
41
|
+
"arguments": { "itemId": 42, "limit": 10 }
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
## Conflict detection
|
|
47
|
+
|
|
48
|
+
- Before editing a description, read the latest version and note its `descriptionRevision`.
|
|
49
|
+
- If another agent or user has modified the item since you last read it, reconcile conflicts before writing: reread, merge changes, and pass the latest `expectedDescriptionRevision`.
|
|
50
|
+
- Never overwrite another user's edits without reconciling first.
|
|
51
|
+
|
|
52
|
+
## Comments and activities
|
|
53
|
+
|
|
54
|
+
1. Use `backlog_comments_list` / `backlog_comment_add` to read or record checkpoint comments on a backlog item.
|
|
55
|
+
2. Use `backlog_activities_list` to read the activity history for a backlog item.
|
|
56
|
+
|
|
57
|
+
## Offline / degraded mode
|
|
58
|
+
|
|
59
|
+
If the Notchlet MCP host (`pg.mbintangr.com`) is unreachable:
|
|
60
|
+
|
|
61
|
+
- Continue repository work that does not depend on missing requirements (coding, testing, local verification).
|
|
62
|
+
- Do not claim remote updates succeeded.
|
|
63
|
+
- Record your intended changes locally so they can be synced when the platform returns.
|
|
64
|
+
- Report the synchronization blocker; do not silently proceed with status changes that cannot be verified on the platform.
|
|
65
|
+
|
|
66
|
+
## When to use
|
|
67
|
+
|
|
68
|
+
- Before any planning, implementation, or delivery: resolve the product and item first.
|
|
69
|
+
- When you need to understand what MCP tools are available on the connected Notchlet host.
|
|
70
|
+
- When you need to search across products, documents, backlog items, or tickets.
|
|
71
|
+
- When you need bounded context for one backlog item without dumping the full backlog.
|
|
72
|
+
- When you suspect a conflict on an item's description or status.
|
|
73
|
+
|
|
74
|
+
## When NOT to use
|
|
75
|
+
|
|
76
|
+
- When the product and backlog item are already resolved and you only need to plan, implement, or deliver — use the individual skill instead.
|
|
77
|
+
- When you need to configure the MCP connection itself — use `notchlet-mcp` first.
|
|
78
|
+
|
|
79
|
+
## Related skills
|
|
80
|
+
|
|
81
|
+
- `notchlet-mcp` — configure MCP connection before using platform tools
|
|
82
|
+
- `notchlet-plan` — plan tasks after resolving the backlog item
|
|
83
|
+
- `notchlet-super` — orchestrates the full cycle including platform discovery
|
|
84
|
+
|
|
85
|
+
This skill is the entry point to Notchlet-driven development; `notchlet-plan`, `notchlet-implement`, `notchlet-review`, and `notchlet-deliver` assume the platform and item have already been resolved.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: notchlet-review
|
|
3
|
+
description: Use when reviewing implemented Notchlet backlog work, approving or requesting changes on PRs/MRs, and handling review feedback before delivery. Sits between notchlet-implement and notchlet-deliver in the development cycle.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Notchlet Code Review
|
|
7
|
+
|
|
8
|
+
Review implemented work against acceptance criteria before it is delivered. A backlog item should not move to `DONE` without passing review.
|
|
9
|
+
|
|
10
|
+
## Entry criteria
|
|
11
|
+
|
|
12
|
+
- Implementation is complete and committed on a feature branch.
|
|
13
|
+
- PR/MR is open against the target branch (main/develop).
|
|
14
|
+
- `notchlet-implement` has been run and the item is set to `IN_REVIEW` or ready for review.
|
|
15
|
+
- All focused checks (lint, type, tests) have passed locally.
|
|
16
|
+
|
|
17
|
+
## Review checklist
|
|
18
|
+
|
|
19
|
+
### Requirements coverage
|
|
20
|
+
- [ ] Every acceptance criterion from the backlog item is addressed by the implementation.
|
|
21
|
+
- [ ] No scope creep: nothing implemented that was not requested or accepted.
|
|
22
|
+
- [ ] Edge cases and failure behavior are handled (timeouts, validation errors, unauthorized access).
|
|
23
|
+
|
|
24
|
+
### Code quality
|
|
25
|
+
- [ ] No exposed secrets, credentials, or personal data in the diff.
|
|
26
|
+
- [ ] No unintended files (build artifacts, node_modules, .env, local config) in the diff.
|
|
27
|
+
- [ ] Existing abstractions reused where appropriate; no unnecessary new abstractions.
|
|
28
|
+
- [ ] Authorization, validation, and caller integration are present where required.
|
|
29
|
+
|
|
30
|
+
### Testing
|
|
31
|
+
- [ ] Focused checks suited to the change have passed (lint, type-check, unit tests).
|
|
32
|
+
- [ ] Test output is actual, not invented or assumed.
|
|
33
|
+
- [ ] Pre-existing failures are distinguished from failures caused by the change.
|
|
34
|
+
|
|
35
|
+
### Backlog consistency
|
|
36
|
+
- [ ] The backlog item description matches the implemented behavior.
|
|
37
|
+
- [ ] `expectedDescriptionRevision` was used on any description edits; conflicts reconciled.
|
|
38
|
+
- [ ] Checkpoint comments recorded on the backlog item with approach, changed files, and check outcomes.
|
|
39
|
+
|
|
40
|
+
## Approve or request changes
|
|
41
|
+
|
|
42
|
+
- **Approve:** If all checklist items pass. Set the backlog item to `IN_REVIEW` (or keep it there) and notify the implementer that delivery can proceed via `notchlet-deliver`.
|
|
43
|
+
- **Request changes:** If any checklist item fails. Add a specific comment on the PR/MR and backlog item listing what must be fixed. Do not set the item to `DONE`. Return to `notchlet-implement` until resolved.
|
|
44
|
+
|
|
45
|
+
## Handle review feedback
|
|
46
|
+
|
|
47
|
+
- If the implementer requests clarification or disputes a finding, discuss on the backlog item comment thread, not in private messages.
|
|
48
|
+
- If changes are required, the implementer updates the code, re-runs checks, and re-submits for review.
|
|
49
|
+
- Re-review only the changed files and the specific feedback items, not the entire implementation from scratch.
|
|
50
|
+
|
|
51
|
+
## When to use
|
|
52
|
+
|
|
53
|
+
- After `notchlet-implement` completes and before `notchlet-deliver`.
|
|
54
|
+
- When a PR/MR needs approval or review feedback.
|
|
55
|
+
- When reviewing another agent's or human's implementation against a Notchlet backlog item.
|
|
56
|
+
|
|
57
|
+
## When NOT to use
|
|
58
|
+
|
|
59
|
+
- For initial planning (use `notchlet-plan`).
|
|
60
|
+
- For writing implementation code (use `notchlet-implement`).
|
|
61
|
+
- For final status sync to Notchlet (use `notchlet-deliver`).
|
|
62
|
+
|
|
63
|
+
## Related skills
|
|
64
|
+
|
|
65
|
+
- `notchlet-implement` — implements work before review
|
|
66
|
+
- `notchlet-deliver` — finalizes delivery after review approval
|
|
67
|
+
- `notchlet-platform` — resolves backlog items and reads context for review
|
|
68
|
+
- `notchlet-super` — orchestrates the full cycle including review
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: notchlet-super
|
|
3
|
+
description: Route a Notchlet development request from current workspace state; resume existing work without restarting setup or planning.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Notchlet Super — state-aware router
|
|
7
|
+
|
|
8
|
+
Use this skill to route a request to the smallest relevant Notchlet action. Read current state first; do not replay a generic six-phase setup for every request. Ask only for material decisions or actions that need user authorization.
|
|
9
|
+
|
|
10
|
+
## Route from the user's intent
|
|
11
|
+
|
|
12
|
+
- **Explore / investigate (read-only):** inspect source, tests, documentation, or bounded MCP context. Do not run `notchlet init`, create/convert a change, edit code, transition tasks, sync, checkpoint, or write backlog state unless the user asks.
|
|
13
|
+
- **Plan only (read-only unless asked to persist):** use `notchlet-plan`. Do not implement or deliver. Planning does not require initialization, an epic→story→task hierarchy, or application/change-artifact writes. A local change plan can be created/refined without starting tasks or writing application code. For an existing local change, `notchlet instructions <change> --action plan` gives planning guidance.
|
|
14
|
+
- **Continue / resume:** reuse the identified workspace, product, repository, backlog item, and active change while they remain valid. Run `notchlet status <change-id>` and `notchlet instructions <change-id> --action resume`; continue only eligible tasks. Do not recreate the plan or restart setup when current state is valid. `notchlet instructions <change> --action resume` provides guidance for resuming a local change.
|
|
15
|
+
- **Revise requirements or design:** use `notchlet-plan` and `notchlet instructions <change-id> --action revise`; preserve stable IDs and existing progress. Revalidate before implementation. `notchlet instructions <change> --action revise` gives revision guidance for an existing local change.
|
|
16
|
+
- **Implement / verify:** use `notchlet-implement`, `notchlet instructions <change-id> --action implement|verify`, and the repository's actual test commands. Mark a task complete only after its verification evidence exists. For an existing local change, use `notchlet instructions <change> --action implement` or `--action verify` as appropriate. Use `notchlet task start <task-id> --change <id> --revision <revision>` and `notchlet task complete <task-id> --change <id> --revision <revision>` for revision-checked local task transitions; `notchlet task update <change> <task> <status> <revision>` supports explicit status changes.
|
|
17
|
+
- **Review:** use `notchlet-review`; distinguish a self-recorded check from independent human review.
|
|
18
|
+
- **Deliver:** use `notchlet-deliver`. A branch-linked item requires the exact linked PR/MR to be merged and approved before a `DONE` status request. Delivery only evaluates existing provider state; it does not merge or deploy.
|
|
19
|
+
|
|
20
|
+
## Reuse current workspace and connection
|
|
21
|
+
|
|
22
|
+
1. Use the nearest initialized `.notchlet` workspace or the user's explicit `--workspace <path>`.
|
|
23
|
+
2. If there is no initialized workspace, local reads are side-effect free. Run `notchlet init` only when setup is actually required and the user approves it; do not assume a separate bootstrap command exists.
|
|
24
|
+
3. For connected work, use `notchlet doctor` to test authenticated capabilities and identity. Do not probe `/mcp` with an unauthenticated `GET`; Notchlet MCP uses authenticated Streamable HTTP `POST` requests.
|
|
25
|
+
4. Do not transfer numeric product IDs between servers. Rebind only after confirming the intended server/product/repository identity.
|
|
26
|
+
5. Fetch bounded context for the selected backlog item; never dump the entire product to find one item.
|
|
27
|
+
6. If MCP credentials or connection settings are genuinely missing, use `notchlet-mcp` to configure and verify them; otherwise skip setup and reuse the working binding.
|
|
28
|
+
7. If the requested backlog item or product is not yet identified, use `notchlet-platform`; if the identity is already confirmed, reuse it instead of searching again.
|
|
29
|
+
|
|
30
|
+
For local readiness checks, run `notchlet validate <id>`; `notchlet change list` lists local changes.
|
|
31
|
+
|
|
32
|
+
## State-aware MCP tool calls
|
|
33
|
+
|
|
34
|
+
The local Notchlet MCP registry exposes these concrete tool names and arguments; use the connected server's `tools/list` schemas as authoritative. Some hosts wrap tool names with a `notchlet_` prefix; call only the exact names actually advertised, and do not assume the new development tools are deployed on every server:
|
|
35
|
+
|
|
36
|
+
- `backlog_development_context({ itemId, section?, cursor?, knownFingerprint?, limit? })` for one bounded item context.
|
|
37
|
+
- `development_changes_list({ productId?, limit?, cursor? })` and `development_change_get({ changeId })` to discover/read changes.
|
|
38
|
+
- `development_instructions_get({ changeId, action, snapshotRevision?, context? })` for server-evaluated instructions tied to a synchronized revision.
|
|
39
|
+
- `development_delivery_create({ changeId, expectedRevision, operationId, payloadHash, snapshotRevision, target, backlogStatus?, repositoryRef?, summary? })` for an explicit, idempotent delivery evaluation. `backlogStatus` additionally requires `backlog:write`; query the operation after an uncertain response and use a new operation ID only for a new attempt.
|
|
40
|
+
|
|
41
|
+
The REST API and MCP tools call the same `DevelopmentService`; preserve their expected revisions, operation IDs, payload hashes, scope checks, and error recovery semantics. Do not infer that remote snapshot state represents unsynchronized local edits.
|
|
42
|
+
|
|
43
|
+
## Authorization and handoff
|
|
44
|
+
- Preserve explicit authorization boundaries. Never push, open/merge a PR, deploy, publish skills, or change remote status merely because a task is complete.
|
|
45
|
+
- Use `notchlet sync status|push|pull --change <id>` for explicit snapshot synchronization. Divergence requires review; use `notchlet sync resolve --change <id> --keep-local` only after reviewing the local artifacts, then retry conditionally.
|
|
46
|
+
- `notchlet checkpoint --change <id> --name <name>` records a synchronized checkpoint; it is not delivery evidence by itself.
|
|
47
|
+
- Local verification, local closure, remote delivery, merge, and deployment are separate outcomes. Never describe merge as deployment or a requested status as successful until the service response confirms it.
|
package/package.json
CHANGED
|
@@ -1,6 +1 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@notchlet/cli",
|
|
3
|
-
"version": "0.0.0-stage",
|
|
4
|
-
"stub": true,
|
|
5
|
-
"description": "Temporary package placeholder for staged publishing"
|
|
6
|
-
}
|
|
1
|
+
{"name":"@notchlet/cli","version":"0.2.0","type":"module","engines":{"node":">=22"},"bin":{"notchlet":"./dist/cli.js"},"files":["dist/cli.js","dist/auth.js","dist/cli-format.js","dist/cli-prompt.js","dist/guidance-install.js","dist/integration.js","dist/setup.js","guidance","scripts/generate-guidance.mjs"],"scripts":{"build":"tsc -p tsconfig.json","test":"npm run build && node --test dist/*.test.js","prepublishOnly":"npm test","guidance:generate":"node scripts/generate-guidance.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.32.2","@napi-rs/keyring":"^2.1.2","@notchlet/core":"^0.1.0"},"devDependencies":{"@types/node":"^22.15.0","typescript":"^5.8.3"}}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
|
|
6
|
+
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
7
|
+
const repositoryRoot = path.resolve(packageRoot, '..');
|
|
8
|
+
const skillsRepoRoot = path.resolve(repositoryRoot, 'notchlet-skills');
|
|
9
|
+
const skillsSourceDir = path.join(skillsRepoRoot, 'skills');
|
|
10
|
+
const sourcePath = path.join(skillsSourceDir, 'notchlet-super', 'SKILL.md');
|
|
11
|
+
const source = await readFile(sourcePath, 'utf8');
|
|
12
|
+
|
|
13
|
+
const requiredCommands = [
|
|
14
|
+
"command === 'init'", "command === 'doctor'", "command === 'workspace'", "command === 'sync'",
|
|
15
|
+
"command === 'checkpoint'", "command === 'instructions'", "command === 'status'", "command === 'task'",
|
|
16
|
+
"command === 'change'", "command === 'validate'", "command === 'backlog'", "command === 'evidence'",
|
|
17
|
+
];
|
|
18
|
+
const cliSource = await readFile(path.join(packageRoot, 'src', 'cli.ts'), 'utf8');
|
|
19
|
+
for (const command of requiredCommands) if (!cliSource.includes(command)) throw new Error(`Guidance references an unavailable CLI command: ${command}`);
|
|
20
|
+
for (const syntax of ['sync status|push|pull|resolve --change', 'checkpoint --change', 'evidence record --change', 'instructions <change> [--action plan|revise|implement|verify|resume]', 'change new <name>', 'change list', 'change show <id>', 'change convert <id>', 'status [change]', 'validate <change>', 'task start <task-id> --change <id> --revision <n>', 'task complete <task-id> --change <id> --revision <n>', 'backlog import <item-id>']) {
|
|
21
|
+
if (!cliSource.includes(syntax)) throw new Error(`Guidance syntax is not present in CLI help: ${syntax}`);
|
|
22
|
+
}
|
|
23
|
+
for (const action of ['plan', 'revise', 'implement', 'verify', 'resume']) {
|
|
24
|
+
if (!cliSource.includes(`'${action}'`)) throw new Error(`Guidance references an unsupported workflow action: ${action}`);
|
|
25
|
+
if (!source.includes(`--action ${action}`)) throw new Error(`Canonical guidance does not reference its declared workflow action: ${action}`);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const skillLock = JSON.parse(await readFile(path.join(skillsRepoRoot, 'skills-lock.json'), 'utf8'));
|
|
29
|
+
const aliases = JSON.parse(await readFile(path.join(packageRoot, 'guidance', 'aliases.json'), 'utf8'));
|
|
30
|
+
const requiredSkills = ['notchlet-mcp', 'notchlet-platform', 'notchlet-plan', 'notchlet-implement', 'notchlet-review', 'notchlet-deliver'];
|
|
31
|
+
for (const skill of requiredSkills) {
|
|
32
|
+
if (!skillLock.skills?.[skill]) throw new Error(`Guidance references a skill missing from skills-lock.json: ${skill}`);
|
|
33
|
+
if (!source.includes(`\`${skill}\``)) throw new Error(`Canonical guidance does not reference its declared skill: ${skill}`);
|
|
34
|
+
}
|
|
35
|
+
for (const [legacy, migration] of Object.entries(aliases.aliases ?? {})) {
|
|
36
|
+
for (const skill of migration.skills ?? []) if (!skillLock.skills?.[skill]) throw new Error(`Alias ${legacy} maps to a skill missing from skills-lock.json: ${skill}`);
|
|
37
|
+
for (const command of migration.commands ?? []) if (!cliSource.includes(command)) throw new Error(`Alias ${legacy} maps to an unsupported CLI command: ${command}`);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const toolRoot = path.resolve(repositoryRoot, 'notchlet', 'notchlet-be', 'src', 'mcp', 'tools');
|
|
41
|
+
const toolFiles = [
|
|
42
|
+
path.join(toolRoot, 'lifecycle.tools.ts'),
|
|
43
|
+
path.join(toolRoot, 'development.tools.ts'),
|
|
44
|
+
];
|
|
45
|
+
const toolSources = await Promise.all(toolFiles.map(file => readFile(file, 'utf8')));
|
|
46
|
+
const requiredTools = {
|
|
47
|
+
backlog_development_context: ['itemId', 'section', 'cursor', 'knownFingerprint', 'limit'],
|
|
48
|
+
development_changes_list: ['productId', 'limit', 'cursor'],
|
|
49
|
+
development_change_get: ['changeId'],
|
|
50
|
+
development_instructions_get: ['changeId', 'action', 'snapshotRevision', 'context'],
|
|
51
|
+
development_delivery_create: ['changeId', 'expectedRevision', 'operationId', 'payloadHash', 'snapshotRevision', 'target', 'backlogStatus', 'repositoryRef', 'summary'],
|
|
52
|
+
};
|
|
53
|
+
for (const [name, args] of Object.entries(requiredTools)) {
|
|
54
|
+
const definition = toolSources.flatMap(text => text.split(/\r?\n/)).find(line => line.includes(`name: '${name}'`));
|
|
55
|
+
if (!definition) throw new Error(`Guidance references an MCP tool not registered by the server: ${name}`);
|
|
56
|
+
for (const arg of args) if (!definition.includes(arg)) throw new Error(`Guidance references unsupported ${name} argument: ${arg}`);
|
|
57
|
+
if (!source.includes(`\`${name}({`)) throw new Error(`Canonical guidance does not reference its declared MCP tool: ${name}`);
|
|
58
|
+
}
|
|
59
|
+
const developmentToolSource = toolSources[1];
|
|
60
|
+
for (const action of ['plan', 'revise', 'implement', 'verify', 'resume']) {
|
|
61
|
+
if (!developmentToolSource.includes(`'${action}'`)) throw new Error(`Guidance references an unsupported development MCP action: ${action}`);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
if (/notchlet-init|curl\s+[^\n]*\/mcp/i.test(source)) throw new Error('Canonical guidance contains a stale init or unauthenticated MCP GET assumption.');
|
|
65
|
+
if (!/Explore \/ investigate \(read-only\)[\s\S]*?Do not run `notchlet init`/.test(source)) throw new Error('Explore guidance must explicitly be read-only and avoid initialization.');
|
|
66
|
+
if (!/Plan only \(read-only unless asked to persist\)[\s\S]*?does not require initialization, an epic→story→task hierarchy, or application\/change-artifact writes/.test(source)) throw new Error('Planning guidance must be read-only by default and independent of initialization and backlog hierarchy.');
|
|
67
|
+
|
|
68
|
+
const clients = ['opencode', 'claude-code'];
|
|
69
|
+
const skillDirs = await readdir(skillsSourceDir);
|
|
70
|
+
const skillEntries = [];
|
|
71
|
+
for (const dir of skillDirs) {
|
|
72
|
+
const skillFile = path.join(skillsSourceDir, dir, 'SKILL.md');
|
|
73
|
+
let st;
|
|
74
|
+
try { st = await stat(skillFile); } catch { st = null; }
|
|
75
|
+
if (!st || !st.isFile()) continue;
|
|
76
|
+
const content = await readFile(skillFile, 'utf8');
|
|
77
|
+
skillEntries.push({ name: dir, content, hash: createHash('sha256').update(content).digest('hex') });
|
|
78
|
+
}
|
|
79
|
+
// Use local guidance/notchlet-super.md as canonical source for notchlet-super skill
|
|
80
|
+
const localSuperSource = await readFile(sourcePath, 'utf8');
|
|
81
|
+
for (const entry of skillEntries) {
|
|
82
|
+
if (entry.name === 'notchlet-super') {
|
|
83
|
+
entry.content = localSuperSource;
|
|
84
|
+
entry.hash = createHash('sha256').update(localSuperSource).digest('hex');
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const targets = [];
|
|
89
|
+
for (const client of clients) {
|
|
90
|
+
for (const entry of skillEntries) {
|
|
91
|
+
const target = path.join(packageRoot, 'guidance', 'generated', client, entry.name, 'SKILL.md');
|
|
92
|
+
await mkdir(path.dirname(target), { recursive: true });
|
|
93
|
+
await writeFile(target, entry.content, 'utf8');
|
|
94
|
+
targets.push({ client, path: path.relative(packageRoot, target).replace(/\\/g, '/'), sha256: entry.hash, skill: entry.name });
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const packageManifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
|
|
99
|
+
const skillsMap = {};
|
|
100
|
+
for (const e of skillEntries) skillsMap[e.name] = { hash: e.hash, path: `skills/${e.name}/SKILL.md` };
|
|
101
|
+
const manifest = {
|
|
102
|
+
manifestVersion: 1,
|
|
103
|
+
source: 'skills/notchlet-super/SKILL.md',
|
|
104
|
+
sourceVersion: packageManifest.version,
|
|
105
|
+
sourceSha256: createHash('sha256').update(source).digest('hex'),
|
|
106
|
+
skillsRepo: skillsRepoRoot,
|
|
107
|
+
skillCount: skillEntries.length,
|
|
108
|
+
skills: skillsMap,
|
|
109
|
+
targets,
|
|
110
|
+
};
|
|
111
|
+
const manifestDir = path.join(packageRoot, 'guidance', 'generated');
|
|
112
|
+
await mkdir(manifestDir, { recursive: true });
|
|
113
|
+
await writeFile(path.join(manifestDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
|
|
114
|
+
await writeFile(path.join(manifestDir, 'compatibility.json'), `${JSON.stringify({ skills: skillLock.skills, aliases: aliases.aliases, source: aliases.source }, null, 2)}\n`, 'utf8');
|
|
115
|
+
console.log(`Synced ${targets.length} skill outputs (${skillEntries.length} skills x ${clients.length} clients) from ${skillsRepoRoot} to guidance/generated/.`);
|
package/README.md
DELETED