@weave-tools/weave-it 0.1.0

package/templates/skills/weave-execute/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: weave-execute
+description: Execute selected local Weave tasks for an active change by preparing branches, implementing tasks, running verification, and updating tasks.md evidence without committing, pushing, or opening PRs.
+last_changed_in: 0.1.0
+---
+
+# Weave Execute
+
+Use this skill when the user wants an agent to execute selected `T#` tasks in an active Weave change.
+
+Execution means: resolve the active change, read `tasks.md`, resolve the user's selector, expand dependencies from `Blocked by:`, run prepare for the final task set, implement each eligible task, run appropriate verification, update local task evidence, and summarize outcomes.
+
+Execution is local-only. It must not commit, push, open pull requests, create remote branches, stash, discard changes, force-checkout, publish external issue updates, or create a separate execution run-history artifact.
+
+# Silent Weave Command Output
+
+Weave skills run Weave CLI commands silently by default. Use command results
+as internal context, not response content.
+
+Do not show raw stdout, JSON payloads, command echoes, lifecycle payloads,
+internal state-write confirmations, or verbatim notice text unless the user
+explicitly asks for diagnostic output.
+
+Surface only information that changes what the user or agent should do next:
+blockers, failures, missing relevant repos, branch or task outcomes,
+lifecycle failures, package-outdated notices, relevant outdated or modified
+skills, and user-required actions.
+
+Notice handling:
+
+- `package_outdated`: show only when present. Say exactly:
+  `A newer Weave version is available. Run \`weave status\` for details, then upgrade Weave when convenient.`
+- `skills_outdated`: suppress unrelated skills. If the invoked skill is outdated, say:
+  `The installed \`<skill-name>\` skill appears older than the bundled template. Run \`weave status\` for details, then \`weave agent update --all\` when you want to refresh installed skills.`
+- `skills_outdated`: if multiple skills used in this workflow are outdated, say:
+  `Some installed skills used in this workflow appear older than the bundled templates: \`<skill-a>\`, \`<skill-b>\`. Run \`weave status\` for details, then \`weave agent update --all\` when you want to refresh them.`
+- `skills_modified`: suppress unless the invoked skill is modified locally or the user is asking about skill updates. If the invoked skill is modified, say:
+  `The installed \`<skill-name>\` skill has local edits, so its behavior may differ from the bundled template. Run \`weave status\` or \`weave agent diff\` if you want to inspect the difference.`
+- `skills_modified`: if the user asks to update skills and installed skills have local edits, say:
+  `Some installed skills have local edits. \`weave agent update\` may skip or protect them; run \`weave status\` or \`weave agent diff\` before updating.`
+
+Do not say `Notices: ...`, `The command returned notices`, raw
+`notices[].message`, full notice JSON, or full skill lists unless the user
+asks for diagnostics.
+
+# Resolve Context
+
+Start with Tier 1 context commands:
+
+```bash
+weave workspace --json
+weave change current --json
+weave change status --json
+```
+
+If there is no active change, stop and say that the user needs `weave change new` or `weave change switch` first.
+
+Read the active change's task artifact:
+
+```text
+wiki/changes/<change-id>/tasks.md
+```
+
+If `tasks.md` is missing, stop and tell the user to run `weave-issues` first.
+
+# Selector Handling
+
+Resolve the user's selector before preparing or implementing anything.
+
+Supported invocation shapes:
+
+```text
+/weave-execute
+/weave-execute T3
+/weave-execute T1 T3 T7
+/weave-execute backend
+/weave-execute all
+```
+
+Map user input as follows:
+
+- `all` -> all executable `T#` tasks in the active `tasks.md`
+- Task ids such as `T1` or `T1 T3` -> those explicit task ids
+- A single non-task, non-`all` value such as `backend` -> tasks whose `Scope` matches that value
+
+If invoked without arguments, ask:
+
+```text
+What should I execute: all tasks, a scope like backend, or specific task ids like T1 T3?
+```
+
+When asking, derive available examples from `tasks.md`: include `all`, available `Scope` values, and available `T#` task ids. Do not default to `all`.
+
+If no tasks match the selector, or an explicit task id is missing, stop before prepare or implementation.
+
+# Task Eligibility
+
+Only execute `T#` tasks. Do not execute `QF#` findings or `R#` refactor records directly.
+
+Executable statuses:
+
+- `todo`
+- `in_progress`
+- `not_tested`
+
+Conditionally executable:
+
+- `blocked` only after all listed `Blocked by:` dependencies are resolved in the same run or are already `done`
+
+Skip by default:
+
+- `done`
+- `invalid`
+
+# Dependency Ordering
+
+Use `Blocked by:` as the source of dependency truth.
+
+For explicit task id selectors, if a selected task depends on incomplete tasks outside the explicit selection, tell the user which blockers must be executed first and ask before expanding the run.
+
+For scope and `all` selectors, automatically include required incomplete blocking tasks and execute them before dependent selected tasks.
+
+Stop before prepare or implementation when:
+
+- a dependency references a missing task id
+- a dependency value is unclear and cannot be interpreted as `None` or `T#` ids
+- dependencies form a cycle
+
+If a task fails, continue independent later tasks. Skip downstream tasks whose dependencies failed, and summarize those skips at the end.
+
+# Run Prepare Before Implementation
+
+Run exactly one prepare command for the final selected task set before implementing anything.
+
+Use the deterministic prepare CLI. The CLI owns branch readiness and `status.yml.execution` writes. Do not hand-edit `status.yml` and do not run git checkout commands yourself for this workflow.
+
+Map the final selected tasks to prepare like this:
+
+- all executable tasks selected from `all` -> `weave task prepare --all --json`
+- explicit task ids -> `weave task prepare T1 T3 --json`
+- scope selectors -> `weave task prepare --scope backend --json`
+- dependency-expanded selections that no longer map cleanly to one scope -> `weave task prepare T1 T3 --json`
+
+If the global `weave` command is unavailable in this repo, use the local development form:
+
+```bash
+npm run dev -- task prepare <selector> --json
+```
+
+If prepare reports blockers, stop before implementation. State that no selected implementation repo branches were moved when the prepare result is blocked.
+
+Dirty work already on the expected branch is allowed when prepare succeeds. Dirty work on another branch must be resolved by the user; do not stash, discard, or force-checkout it.
+
+# Execute Tasks
+
+Execute tasks in dependency order.
+
+Before starting each task:
+
+1. Patch only that task's active index row and detail `Status:` to `in_progress`.
+2. Do not rewrite unrelated task wording or unrelated task sections.
+3. For HITL tasks, pause for the required human input before proceeding. `/weave-execute all` includes HITL tasks, but still pauses before each HITL task.
+
+During implementation:
+
+- Use the task's `### What to build`, acceptance criteria, verification guidance, architecture refs, and repo anchors as the implementation contract.
+- Keep edits scoped to the task.
+- If the task exposes missing or ambiguous instructions, ask before guessing.
+
+# Verification
+
+Run task-listed checks first. Then run the smallest relevant broader checks when the task's blast radius warrants it.
+
+Examples:
+
+- a skill packaging change should usually run the relevant `tests/agent-skills.test.ts` tests
+- a CLI or library behavior change should usually run targeted tests plus typecheck when practical
+- final cross-cutting verification may run `npm run typecheck`, `npm test`, and `npm run build`
+
+If verification cannot run, explain why. Mark a task `not_tested` only when implementation appears complete but verification could not be completed.
+
+# Task Artifact Updates
+
+Update `tasks.md` directly and narrowly.
+
+Allowed updates for affected tasks:
+
+- active task index status
+- detail section `Status:`
+- acceptance criteria checkboxes that were actually satisfied
+- concise verification notes under the affected task's `### Verification` section
+
+Status rules:
+
+- set `in_progress` when work begins for a task
+- set `done` only when implementation is complete and verification passes
+- set `not_tested` when implementation appears complete but verification could not run
+- leave or set `in_progress` with notes when implementation is incomplete or verification fails
+- skip `done` and `invalid` tasks by default
+
+Do not rewrite unrelated task wording, unrelated task sections, `QF#` entries, `R#` entries, invalid task history, or global task sections unless the selected task's own evidence requires a narrow local note.
+
+# Final Summary
+
+Finish with a grouped outcome summary:
+
+- completed tasks
+- tasks left `not_tested`
+- failed or still-`in_progress` tasks
+- skipped tasks, including `done`, `invalid`, or dependency-blocked tasks
+- prepare blockers, if any
+- verification commands or checks that passed, failed, or could not run
+- next steps for anything unresolved
+
+Always state that `/weave-execute` did not commit, push, open a PR, create remote branches, stash, discard changes, or publish external issue updates.

package/templates/skills/weave-explore/SKILL.md

@@ -0,0 +1,434 @@
+---
+name: weave-explore
+description: Stress-test product requirements against the current system, workflows, and domain language. Use when refining PRDs, validating workflows, uncovering edge cases, clarifying ownership, or aligning new changes with existing product behavior.
+last_changed_in: 0.1.0
+---
+
+# Weave Awareness
+
+This is a Weave product exploration skill.
+
+---
+
+# Plan Mode Guard
+
+This skill must run in Plan Mode.
+
+If the current environment exposes collaboration mode and it is not Plan Mode, stop immediately and say:
+
+`This skill must run in Plan Mode. Switch to Plan Mode, then invoke weave-explore again.`
+
+Do not inspect deeply, ask discovery questions, update artifacts, or continue work before this guard passes.
+
+Static Weave skill content cannot automatically switch collaboration mode. The host, user, or developer layer must switch modes before this skill continues.
+
+In Plan Mode, this skill commits the active artifact lane to local Weave session state via:
+
+```bash
+weave artifact current set exploration --json
+```
+
+This writes local Weave session state only. It does not write repo-tracked artifacts and IS allowed in Plan Mode. Call it after resolving the active Weave change and before any other discovery work.
+
+Do not write repo-tracked artifacts directly. Produce the plan, decisions, questions, or proposed artifact changes needed for the user to approve. Actual artifact writes happen only after the user exits Plan Mode and asks to implement the plan.
+
+---
+
+Start by discovering the current Weave session:
+
+```bash
+weave workspace --json
+weave change current --json
+weave artifact current set exploration --json
+```
+
+Use the cwd-dispatched workspace or repo context returned by `weave workspace --json` as the exploration boundary. In workspace mode, the workspace root owns the change store and registered sub-repos in `repos[]` are implementation locations inside that single context. In repo mode, the active session's folders are the boundary. If there is no active Weave change, stop and ask the user to run `weave change new` or `weave change switch` before continuing.
+
+# Workspace Repo Context Protocol
+
+When `weave workspace --json` returns a `workspace` object, treat `workspace.path` as the single Weave change artifact root. Registered entries in `repos[]` are implementation and documentation locations inside that workspace, not separate artifact targets.
+
+Do not create, read, or update change artifacts under each sub-repo by default. Durable change artifacts remain under:
+
+```text
+<workspace.path>/wiki/changes/<change-id>/
+```
+
+Before deep inspection, build a lightweight repo context map from `repos[]`:
+
+- repo id
+- repo path
+- repo kind
+- remote, when present
+- whether the repo appears relevant to the current user request
+- docs and knowledge surfaces present, such as `README.md`, `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/`, `docs/adr/`, `adr/`, `wiki/knowledge/`, `wiki/changes/`, `specs/`
+- obvious code/test surfaces that may verify current behavior
+
+Lightly inventory all registered repos. Deeply inspect only repos that appear relevant from the user's request, active change artifacts, repo names/kinds, docs, knowledge, prior changes, or code references.
+
+Prefer current docs, knowledge specs, ADRs, and repo-local Weave wiki content before reading implementation code. Use code and tests to verify important claims from docs or memory.
+
+If a repo is skipped, keep the reason simple: unrelated name/kind, no matching docs, no matching code references, or out of scope for the current question.
+
+When presenting findings, include a short context note:
+
+```text
+Context loaded:
+- Workspace artifact root: <path>
+- Repos inspected: <repo ids>
+- Repo docs/knowledge read: <paths>
+- Code/test anchors read: <paths>
+- Repos skipped: <repo id> (<reason>)
+```
+
+Do not exhaustively scan every repo unless the user explicitly asks for a workspace-wide audit.
+
+---
+
+For each resolved context, inspect Weave knowledge first when present:
+
+```text
+wiki/knowledge/index.md
+wiki/knowledge/README.md
+wiki/knowledge/domains/**/index.md
+wiki/knowledge/domains/**/features/**/behavior.md
+wiki/knowledge/domains/**/domain-wide/**
+wiki/knowledge/shared/**/behavior.md
+wiki/knowledge/**/source-map.md
+wiki/changes/
+```
+
+Use `wiki/knowledge/` as current product/domain context.
+
+Use `wiki/changes/` as historical or in-progress change context.
+
+If a relevant change folder exists, read the applicable change artifacts:
+
+```text
+exploration.md
+prd.md
+sessions/*-exploration.md
+decisions.md
+contracts.md
+status.yml
+handoff.md
+implementation.md
+tasks.md
+```
+
+In workspace mode there is one change context: the workspace root. In repo mode, do not assume every session folder is equally relevant; identify which contexts appear relevant and why.
+
+---
+
+# Resume Context
+
+`weave-explore` means enter or resume exploration for the active change.
+
+When an active change already has exploration context, resume before asking new discovery questions:
+
+1. Read `wiki/changes/<change-id>/exploration.md` first. Treat the live artifact as canonical current truth.
+2. Read relevant `wiki/changes/<change-id>/sessions/*-exploration.md` files newest-first.
+3. Prioritize the latest `## Next Resume Point` when deciding what to ask or examine next.
+4. Use older exploration session files only when needed for rationale, unresolved points, user preferences, or agent recommendations.
+5. If session notes conflict with the live artifact, prefer the live artifact unless the latest session records an explicit newer user decision.
+6. If the user gives an explicit direction, follow it over the stored resume point.
+
+At the start of a resumed exploration, briefly state what was loaded:
+
+```text
+Resuming exploration for <change-id>.
+Loaded exploration.md and <N> exploration session note(s).
+Latest resume point: <summary>
+```
+
+If no useful prior exploration content or session notes exist, start normal exploration.
+
+---
+
+# Purpose
+
+This skill helps refine product requirements by interrogating workflows, domain language, permissions, lifecycle behavior, operational expectations, and edge cases.
+
+The goal is to clarify:
+- what the system should do
+- who experiences it
+- how it behaves in real scenarios
+- how it fits into the existing product model
+
+This is a product discovery and requirement clarification exercise - not an architecture review.
+
+---
+
+# Core Behavior
+
+Interview the user relentlessly about the product behavior until a shared understanding is reached.
+
+Ask questions one at a time and wait for the user's response before continuing.
+
+For each question:
+- explain why the question matters
+- provide a likely/default recommendation
+- explain implications of alternative choices
+- keep the discussion grounded in user and business behavior
+- avoid implementation details unless explicitly requested
+
+Prefer:
+- concrete scenarios
+- user journeys
+- lifecycle transitions
+- ownership clarification
+- operational edge cases
+
+Avoid:
+- infrastructure discussions
+- database choices
+- eventing strategies
+- APIs
+- storage design
+- deployment architecture
+- framework discussions
+
+unless the user explicitly asks for technical design.
+
+---
+
+# Discovery Order
+
+Resolve questions in this order:
+
+1. Domain language
+2. Users, actors, and roles
+3. User workflows
+4. Permissions and admin controls
+5. State transitions and lifecycle rules
+6. Failure cases and edge cases
+7. Notifications and visibility
+8. Operational expectations
+9. Rollout flags, configuration, rollout scope, and migration concerns
+10. Technical implications (only if required)
+
+Do not jump into technical implementation prematurely.
+
+---
+
+# Technical Boundary
+
+You may inspect the codebase to:
+- understand existing workflows
+- identify terminology
+- discover current constraints
+- detect contradictions
+- understand current product behavior
+- uncover hidden assumptions
+
+Use the codebase to anchor the conversation in reality.
+
+But do NOT ask users to choose:
+- databases
+- queues
+- event buses
+- consistency models
+- storage engines
+- deployment patterns
+- API styles
+- frameworks
+
+unless:
+1. the user explicitly requests technical design
+2. or the decision materially changes product behavior, compliance, or operational guarantees
+
+If a technical concern emerges:
+- capture it as a technical implication
+- do not force resolution immediately
+- continue product discovery first
+
+Translate technical concerns into behavioral language whenever possible.
+
+Example:
+Instead of asking:
+> "Should this be eventually consistent?"
+
+Ask:
+> "Is it acceptable if users see updates a few seconds later?"
+
+---
+
+# Sub-Repo Product Discovery
+
+In workspace mode, use registered repos to understand existing product behavior across the workspace.
+
+For relevant repos, prioritize reading:
+
+```text
+wiki/knowledge/**
+wiki/changes/**
+README.md
+CONTEXT.md
+CONTEXT-MAP.md
+docs/**
+docs/adr/**
+adr/**
+specs/**
+tests/**
+```
+
+Use sub-repo context to discover:
+
+- domain language and user-facing terminology
+- actors, roles, permissions, and ownership boundaries
+- existing workflows and lifecycle states
+- configuration or rollout behavior that changes user experience
+- failure states, edge cases, and operational expectations
+- prior changes or specs that constrain the current exploration
+
+Read implementation code only as needed to verify current behavior, locate hidden assumptions, or resolve contradictions between docs and reality.
+
+Translate technical findings into product behavior questions. Do not ask the user to choose implementation details unless the choice materially changes user behavior, compliance, visibility, permissions, rollout, or operational guarantees.
+
+---
+
+# Scenario-Driven Discovery
+
+Prefer concrete scenarios over abstractions.
+
+Instead of:
+> "Can approvals be revoked?"
+
+Ask:
+> "Suppose compensation is finalized and a manager reopens the review afterward - what should happen?"
+
+Use scenarios to:
+- expose hidden assumptions
+- clarify ownership
+- test lifecycle boundaries
+- uncover operational risks
+- reveal conflicting expectations
+
+---
+
+# Domain Awareness
+
+During codebase exploration, also look for existing documentation. Prefer Weave knowledge when present, and use existing repo documentation as additional context.
+
+## File structure
+
+Most repos have a single context:
+
+```text
+/
+|-- CONTEXT.md
+|-- docs/
+|   `-- adr/
+`-- src/
+```
+
+Some repos have multiple contexts:
+
+```text
+/
+|-- CONTEXT-MAP.md
+|-- docs/
+|   `-- adr/
+`-- src/
+    |-- ordering/
+    |   |-- CONTEXT.md
+    |   `-- docs/adr/
+    `-- billing/
+        |-- CONTEXT.md
+        `-- docs/adr/
+```
+
+Use existing documentation to:
+- align terminology
+- avoid duplicate concepts
+- detect conflicting meanings
+- understand established workflows
+- reconcile Weave knowledge with repo-local docs when they conflict
+
+---
+
+# PM-Safe Code Exploration
+
+Code inspection is allowed when needed to verify current product behavior.
+
+However, do not show code snippets, function internals, database schemas, API details, or infrastructure details unless the user explicitly asks.
+
+Translate technical findings into product language.
+
+Good:
+> "Today, the system appears to finalize the whole review at once. It does not currently support partial approvals."
+
+Avoid unless asked:
+> "The `finalizeReview()` function calls `updateMany()` on all review items."
+
+If technical uncertainty matters, surface it as a product-relevant implication:
+> "There may be technical coupling here, but the product question is whether partial approval should exist at all."
+
+Keep technical implications separate from product decisions.
+
+---
+
+# Glossary Discipline
+
+Challenge terminology aggressively.
+
+If the user uses a term that conflicts with the existing language, call it out immediately.
+
+Example:
+> "Your glossary defines 'submission' differently from how you're using it here - which meaning should we standardize on?"
+
+Sharpen vague language.
+
+Replace overloaded terms with precise domain concepts.
+
+Example:
+> "When you say 'manager', do you mean the direct manager, calibration owner, or workflow approver?"
+
+Do not allow ambiguous terminology to survive.
+
+---
+
+# Cross-Reference With Reality
+
+When the user describes behavior:
+- verify whether the existing system already behaves differently
+- inspect workflows if necessary
+- surface contradictions explicitly
+
+Example:
+> "You mentioned partial approvals are allowed, but the current workflow finalizes the entire review together. Which behavior should be authoritative?"
+
+Treat the current product behavior as an important input - but not necessarily the correct future behavior.
+
+---
+
+# Silent Weave Command Output
+
+Weave skills run Weave CLI commands silently by default. Use command results
+as internal context, not response content.
+
+Do not show raw stdout, JSON payloads, command echoes, lifecycle payloads,
+internal state-write confirmations, or verbatim notice text unless the user
+explicitly asks for diagnostic output.
+
+Surface only information that changes what the user or agent should do next:
+blockers, failures, missing relevant repos, branch or task outcomes,
+lifecycle failures, package-outdated notices, relevant outdated or modified
+skills, and user-required actions.
+
+Notice handling:
+
+- `package_outdated`: show only when present. Say exactly:
+  `A newer Weave version is available. Run \`weave status\` for details, then upgrade Weave when convenient.`
+- `skills_outdated`: suppress unrelated skills. If the invoked skill is outdated, say:
+  `The installed \`<skill-name>\` skill appears older than the bundled template. Run \`weave status\` for details, then \`weave agent update --all\` when you want to refresh installed skills.`
+- `skills_outdated`: if multiple skills used in this workflow are outdated, say:
+  `Some installed skills used in this workflow appear older than the bundled templates: \`<skill-a>\`, \`<skill-b>\`. Run \`weave status\` for details, then \`weave agent update --all\` when you want to refresh them.`
+- `skills_modified`: suppress unless the invoked skill is modified locally or the user is asking about skill updates. If the invoked skill is modified, say:
+  `The installed \`<skill-name>\` skill has local edits, so its behavior may differ from the bundled template. Run \`weave status\` or \`weave agent diff\` if you want to inspect the difference.`
+- `skills_modified`: if the user asks to update skills and installed skills have local edits, say:
+  `Some installed skills have local edits. \`weave agent update\` may skip or protect them; run \`weave status\` or \`weave agent diff\` before updating.`
+
+Do not say `Notices: ...`, `The command returned notices`, raw
+`notices[].message`, full notice JSON, or full skill lists unless the user
+asks for diagnostics.