@weave-tools/weave-it 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@weave-tools/weave-it",
+  "version": "0.1.0",
+  "description": "SDLC package for AI-assisted software teams working across monorepos and multi-repo workspaces.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Arpit Agarwal <agarwalarpit22@gmail.com>",
+  "homepage": "https://github.com/arpit016/weave-it#readme",
+  "bugs": {
+    "url": "https://github.com/arpit016/weave-it/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arpit016/weave-it.git"
+  },
+  "keywords": [
+    "weave",
+    "cli",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "codex",
+    "opencode",
+    "sdlc",
+    "sdd",
+    "spec-driven-development",
+    "wiki",
+    "knowledge-base"
+  ],
+  "bin": {
+    "weave": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "release:bump-skills": "node scripts/bump-skill-versions.mjs",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "version": "npm run release:bump-skills && git add -A templates/skills"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "commander": "^14.0.3",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}

package/templates/opencode/commands/weave-architect.md

@@ -0,0 +1,7 @@
+---
+description: Generate or revise architecture.md from an active Weave PRD
+---
+
+Load and follow the `weave-architect` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-capture.md

@@ -0,0 +1,7 @@
+---
+description: Capture the current discussion into a Weave artifact or session-only note
+---
+
+Load and follow the `weave-capture` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-clarify.md

@@ -0,0 +1,7 @@
+---
+description: Clarify an existing Weave change artifact
+---
+
+Load and follow the `weave-clarify` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-execute.md

@@ -0,0 +1,7 @@
+---
+description: Execute local Weave tasks for an active change
+---
+
+Load and follow the `weave-execute` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-explore.md

@@ -0,0 +1,7 @@
+---
+description: Explore and draft a PRD using Weave context
+---
+
+Load and follow the `weave-explore` skill.
+
+Topic: $ARGUMENTS

package/templates/opencode/commands/weave-issues.md

@@ -0,0 +1,7 @@
+---
+description: Break a Weave plan into local tasks.md implementation tasks
+---
+
+Load and follow the `weave-issues` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-knowledge.md

@@ -0,0 +1,7 @@
+---
+description: Update current-state Weave knowledge specs for an active change
+---
+
+Load and follow the `weave-knowledge` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-new.md

@@ -0,0 +1,7 @@
+---
+description: Start a new Weave change exploration
+---
+
+Load and follow the `weave-new` skill.
+
+Topic: $ARGUMENTS

package/templates/opencode/commands/weave-next.md

@@ -0,0 +1,7 @@
+---
+description: Answer what to do next for the active Weave change
+---
+
+Load and follow the `weave-next` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-prd.md

@@ -0,0 +1,7 @@
+---
+description: Generate or revise a PRD from the active Weave exploration
+---
+
+Load and follow the `weave-prd` skill.
+
+Context: $ARGUMENTS

package/templates/opencode/commands/weave-prepare.md

@@ -0,0 +1,7 @@
+---
+description: Prepare task execution branches for a Weave change
+---
+
+Load and follow the `weave-prepare` skill.
+
+Context: $ARGUMENTS

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

@@ -0,0 +1,291 @@
+---
+name: weave-architect
+description: Read-only thinking partner for active Weave architecture work. Use when the user wants engineering architecture, technical design, implementation strategy, tradeoff analysis, risk review, or a deep dive into an existing architecture facet.
+last_changed_in: 0.1.0
+---
+
+# Weave Architect
+
+This skill is a read-only architecture thinking partner. It gathers context, interviews the user, stress-tests tradeoffs, and produces a clear technical dissection that `weave-capture` can persist later.
+
+It never creates, edits, renames, deletes, or progresses repo-tracked artifacts. It may update local Weave session state only to record that the active artifact lane is `architecture` via `weave artifact current set architecture --json`; this local lane commit is not a repo-tracked artifact write.
+
+It does not read architecture template resources; templates are writer inputs for `weave-capture` and restructuring inputs for `weave-clarify`.
+
+# 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-architect 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 architecture --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.
+
+# Operating Principles
+
+- Treat `weave-architect` as entering or resuming the architecture lane for the active change.
+- Treat `prd.md` as the preferred product contract when it exists and is useful, but do not require it before architecture thinking.
+- Read enough code, docs, ADRs, knowledge specs, and existing Weave artifacts to understand current implementation patterns before recommending design.
+- In workspace mode, inspect registered repo folders as implementation locations inside one shared change context. In repo mode, keep the resolved repo context as the boundary.
+- Support both legacy `wiki/changes/<change-id>/architecture.md` and folder-mode `wiki/changes/<change-id>/architecture/index.md` plus `architecture/*.md` facets.
+- If both `architecture.md` and `architecture/` exist, call out the conflict and ask the user to resolve it with `weave-clarify` or `weave-capture` before relying on either as canonical.
+- Ask focused product questions only when technical design exposes ambiguity not settled by existing artifacts.
+- Do not create implementation issues; use `weave-issues` after the design is captured and ready.
+
+# Resolve Context
+
+Start by discovering the current Weave session and committing the architecture lane to local Weave session state:
+
+```bash
+weave workspace --json
+weave change current --json
+weave change status --json
+weave artifact current set architecture --json
+weave artifact current --json
+```
+
+Setting local artifact context with `weave artifact current set architecture --json` is allowed in Plan Mode because it writes local session state, not repo-tracked change artifacts. Run it as part of this initial discovery sequence, not as a conditional follow-up. Then verify the stored lane with `weave artifact current --json`.
+
+If the lane verification succeeds, keep successful lane entry silent. If the lane verification fails or the stored lane is still not `architecture`, continue the architecture discussion and show only this warning:
+
+```text
+I could not update the stored artifact lane to `architecture`, so `weave-capture` may ask you to confirm the capture target later.
+```
+
+If `weave change current --json` reports no active change, stop and say:
+
+```text
+No active Weave change found. Run `weave change new` or `weave change switch`, then run `weave-architect` again.
+```
+
+Apply the Silent Weave Command Output policy to the commands above.
+
+# 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.
+
+# Architecture Context Loading
+
+Read live artifacts first, then sessions:
+
+```text
+wiki/changes/<change-id>/status.yml
+wiki/changes/<change-id>/exploration.md
+wiki/changes/<change-id>/prd.md
+wiki/changes/<change-id>/architecture.md
+wiki/changes/<change-id>/architecture/index.md
+wiki/changes/<change-id>/architecture/*.md
+wiki/changes/<change-id>/sessions/*-architecture.md
+wiki/changes/<change-id>/knowledge-delta.md
+wiki/changes/<change-id>/tasks.md
+```
+
+Architecture shape rules:
+
+- Legacy file mode: read `architecture.md`.
+- Folder mode: read `architecture/index.md` first when present, then direct child facet files under `architecture/*.md`.
+- Facet-only folder mode is valid context when one or more facet files are substantive even if `index.md` is missing or scaffold-only.
+- Conflict mode exists when both `architecture.md` and `architecture/` exist. Report it explicitly.
+
+For session notes, prefer the latest `## Next Resume Point`, unresolved decisions, and explicit user preferences. If session notes contain `facets: [...]` frontmatter, use it to find relevant facet discussions, but do not require it.
+
+# Codebase And Docs Context
+
+Inspect only context that can materially affect the architecture:
+
+- source modules and tests in the affected repo folders
+- existing internal docs, ADRs, and knowledge specs
+- schemas, migrations, API contracts, event contracts, jobs, config, feature flags, and deployment files
+- adjacent integration boundaries across registered workspace repos
+
+Use existing architecture, framework conventions, helpers, data models, and ADRs before inventing a new abstraction.
+
+# Sub-Repo Architecture Discovery
+
+In workspace mode, use registered repos to understand technical boundaries across the workspace.
+
+For relevant repos, prioritize reading:
+
+```text
+README.md
+CONTEXT.md
+CONTEXT-MAP.md
+docs/**
+docs/adr/**
+adr/**
+specs/**
+wiki/knowledge/**
+wiki/changes/**
+package manifests and build config
+schema and migration files
+API route or contract files
+event, queue, job, or worker definitions
+deployment and runtime config
+tests around integration boundaries
+```
+
+Use sub-repo context to identify:
+
+- affected repos and ownership boundaries
+- cross-repo data flow
+- API, event, job, schema, and deployment contracts
+- shared libraries or duplicated behavior
+- migration and rollout constraints
+- observability, testing, and failure-mode implications
+- architecture decisions already recorded in docs, ADRs, or repo-local wiki content
+
+Docs and ADRs are the first pass. Code and tests are the verification pass.
+
+When returning an architecture dissection, include repo-aware findings when relevant:
+
+```text
+## Workspace Context
+- Affected repos:
+- Repos inspected:
+- Important docs/ADRs:
+- Important code/test anchors:
+- Repos skipped:
+
+## Cross-Repo Architecture
+- Boundaries:
+- Contracts:
+- Data flow:
+- Rollout/migration concerns:
+- Risks:
+```
+
+Keep this skill read-only. Do not create, edit, move, rename, delete, or progress artifacts in any sub-repo.
+
+# Deep Dive Modes
+
+The user may invoke this skill broadly or target a concern:
+
+- broad architecture review for the active change
+- deep dive on a facet file such as `architecture/schema.md`
+- deep dive on a proposed concern such as schema design, API contracts, frontend/backend integration, auth, rollout, or observability
+- deep dive on a code area, repo folder, doc, or existing artifact section
+
+For a targeted deep dive, still load enough surrounding context to avoid local optimization. Do not write the target file.
+
+# Interview Behavior
+
+Interview the user relentlessly about the engineering design until shared technical understanding is reached.
+
+Ask questions one at a time and wait for the user's response before continuing.
+
+For each blocking architecture question:
+
+- explain why the question matters
+- provide a likely/default recommendation
+- explain implications of alternative choices
+- explicitly offer: "Explain with an example before deciding"
+
+If the user asks for an example or explanation before deciding:
+
+- explain the tradeoff with a concrete example grounded in the PRD, architecture context, and codebase
+- restate the original decision question
+- wait for the user's decision before continuing
+
+# Output
+
+Return a structured, readable architecture dissection instead of writing files. Include only sections that are useful for the current discussion.
+
+Recommended shape:
+
+```text
+## Architecture Dissection
+- Current understanding
+- Decisions and recommendations
+- Facets affected
+- Tradeoffs
+- Risks and mitigations
+- Open questions
+- Capture guidance
+```
+
+When useful, name likely destination facets for `weave-capture`, such as `index`, `schema`, `api-contract`, `frontend-backend`, or a user-named facet. This is guidance, not a command.
+
+If the user wants to persist the discussion, recommend:
+
+```text
+Run `weave-capture` to write the architecture discussion into the appropriate architecture artifact files.
+```
+
+# 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.

package/templates/skills/weave-architect/api-contract-template.md

@@ -0,0 +1,21 @@
+---
+facet: api-contract
+description: Request, response, event, and integration contract design.
+---
+
+# API Contract Design
+
+## Consumers And Producers
+- <Callers, owners, services, clients, and external systems involved.>
+
+## Contract Shape
+- <Endpoints, commands, events, payloads, statuses, and errors.>
+
+## Versioning And Compatibility
+- <Rollout, compatibility rules, deprecation, and migration expectations.>
+
+## Authorization And Validation
+- <Permissions, trust boundaries, validation rules, and failure behavior.>
+
+## Observability And Testing
+- <Logs, metrics, contract tests, fixtures, and verification plan.>

package/templates/skills/weave-architect/frontend-backend-template.md

@@ -0,0 +1,21 @@
+---
+facet: frontend-backend
+description: Frontend/backend integration flow and user-facing behavior design.
+---
+
+# Frontend And Backend Integration
+
+## User Flow
+- <User-visible workflow, states, transitions, and error cases.>
+
+## Frontend Responsibilities
+- <UI state, components, routes, client validation, and API usage.>
+
+## Backend Responsibilities
+- <Server behavior, persistence, authorization, background work, and APIs.>
+
+## Integration Contract
+- <Request/response or event flow across the boundary.>
+
+## Rollout And Verification
+- <Feature flags, deployment ordering, telemetry, and test coverage.>

package/templates/skills/weave-architect/index-template.md

@@ -0,0 +1,24 @@
+---
+facet: index
+description: Canonical entry point for a folder-based architecture artifact.
+---
+
+# <Change Name> Architecture
+
+## Decision Summary
+- <Key architectural decisions and rationale.>
+
+## System Context
+- <Current systems, repos, modules, docs, and constraints that matter.>
+
+## Architecture Overview
+- <High-level design and how the pieces fit together.>
+
+## Facets
+- `<facet>.md`: <Purpose and current status.>
+
+## Tradeoffs
+- <Important alternatives considered and why they were accepted or rejected.>
+
+## Risks And Open Questions
+- <Unresolved technical risks, decisions, or follow-up investigations.>

package/templates/skills/weave-architect/schema-template.md

@@ -0,0 +1,21 @@
+---
+facet: schema
+description: Data model, storage, migration, and compatibility design.
+---
+
+# Schema Design
+
+## Current Model
+- <Existing entities, fields, relationships, indexes, and persisted assumptions.>
+
+## Proposed Model
+- <New or changed entities, fields, relationships, indexes, and ownership.>
+
+## Migration Strategy
+- <Backfill, rollout, rollback, and data correction plan.>
+
+## Compatibility
+- <Backward compatibility, read/write transition, and old data handling.>
+
+## Validation And Risks
+- <Invariants, integrity checks, operational risks, and open questions.>