Skip to main content

Core concepts

Plugin​

What it is: Asterweave itself — a Claude Code plugin (plugins/asterweave/) distributed through a marketplace, with a manifest (.claude-plugin/plugin.json), skills, agents, hooks, and an MCP server configuration. What it is not: Not a repository template, not a code generator, not tied to any one codebase. Example: plugin.json declares the plugin name asterweave, its version, and the github_token/ado_organization/ado_pat_base64 user-configuration fields.

Command (skill)​

What it is: A slash command under the /asterweave: namespace, backed by a SKILL.md file with YAML frontmatter (name, description, model, effort, sometimes argument-hint). Sixteen exist today — see the command reference. What it is not: Not a separate CLI binary; it only runs inside Claude Code. Not the same as a project skill — a repository can define its own unscoped skills under .claude/skills/. Example: /asterweave:deliver owner/repo#123 invokes skills/deliver/SKILL.md.

Agent​

What it is: A specialist subagent — a Markdown file under plugins/asterweave/agents/ with a frontmatter tool allowlist (tools:, often disallowedTools:) and a system prompt scoping its one job. Thirteen exist today — see the agent reference. What it is not: Not interchangeable with a skill. A skill is an entry point you or the orchestrator invoke; an agent is what a skill (or the orchestrator) delegates bounded work to, in an isolated context. Example: asterweave:security-reviewer can read and run shell commands but cannot edit files (disallowedTools: Write, Edit, Agent).

Rule​

What it is: Repository-specific, path-scoped guidance under .claude/rules/*.md, generated or refreshed by /asterweave:scaffold from real evidence in your repository — never invented conventions. What it is not: Not a place for product requirements (those belong in specs/) and not a duplicate of a plugin-wide policy Asterweave already enforces (like Git safety or evidence discipline). Example: A rule stating Persistence handlers use ApplicationDbContext directly; do not introduce repository abstractions.

Hook​

What it is: A deterministic Node.js script wired to a Claude Code lifecycle event through hooks/hooks.json. Asterweave ships exactly two: a PreToolUse guard that blocks a fixed list of destructive shell commands, and a Stop gate that keeps an active workflow moving. See Hooks. What it is not: Not a general security boundary or a substitute for Claude Code permissions, sandboxing, and branch protection. Example: The PreToolUse hook denies git push --force origin main before it runs.

Spec​

What it is: A repository's own description of what the system must do — FR-### functional requirements, NFR-### quality attributes, C-### constraints, and UC-### use cases — living under a specs/ directory the repository already owns. See Specifications. What it is not: Not generated by Asterweave scaffolding. Asterweave only reads an existing specs/ directory, or proposes one use case at a time under explicit approval when a normal/complex feature needs it. Example: UC-024-refund.md describing the refund-payment use case, referenced as UC-024 in evidence and PR text.

Workflow (the delivery graph)​

What it is: The deterministic sequence Asterweave's Node scripts drive /asterweave:deliver through: intake → analyze → challenge → plan → approve → implement → test → verify → review → submit-pr → monitor-pipeline → resolve-review-comments → update-work-item → done. See Architecture overview. What it is not: Not a suggestion the model can skip — the graph, not narrative confidence, decides whether a node has passed. Example: A test failure routes back to implement (fail-retryable), which invalidates and re-runs test, verify, review, and submit-pr for the new change.

Context manifest​

What it is: A bounded JSON file (.claude/asterweave/context-manifest.json) written when analyze passes, holding the task/source reference, applicable rules and spec files, representative implementation/test files, and affected paths — so later nodes don't re-scan the whole repository. What it is not: Not a committed artifact; it is workflow state, superseded by the next analyze pass. Example: challenge, plan, implement, test, verify, and review read it first before expanding their own search.

Workflow state​

What it is: The durable, typed record of an in-progress delivery — .claude/asterweave/state.json plus an append-only .claude/asterweave/events.jsonl ledger, owned exclusively by scripts/graph-state.mjs. See Workflow state. What it is not: Not conversation memory. A new Claude Code session can resume a workflow purely from these files. Example: node .../graph-state.mjs status --compact reports the current node, attempts used, and outstanding evidence.

Repository scaffold​

What it is: The output of /asterweave:scaffold — an evidence-backed CLAUDE.md, .claude/rules/*.md, project skills/agents, .claude/references/*.md, and .claude/asterweave.json, produced by its own approval-gated graph (discover → model → propose → audit → approve → apply → validate). See Repository scaffolding. What it is not: Not a one-shot template stamp; it is a reconciler that preserves useful existing content and flags — but never silently deletes — stale artifacts. Example: Scaffolding removes a repository's hand-rolled deliver.md command once Asterweave's own /asterweave:deliver supersedes it, but keeps a genuinely domain-specific finance-reviewer agent.

Agent routing (the repository adapter)​

What it is: .claude/asterweave.json's routing map, which can point a graph stage (analyze, challenge, plan, implement, test, verify, review, submit-pr, monitor-pipeline, resolve-review-comments, update-work-item) at a project-specific agent and project skills instead of Asterweave's generic specialist. See Agent routing. What it is not: Not a way to bypass a gate — routing can only add checks or narrow permissions, never remove approval, evidence, testing, verification, review, security, or Git-safety requirements. Example: Routing implement to a repository's payments-implementer agent for a payments-domain change.

Verification gate (evidence)​

What it is: The requirement that every node's exit claim be backed by an environment-grounded evidence record — a command, its result, and an artifact reference — not a model's summary. What it is not: Not "the tests probably pass" or "this looks correct." A passing unit test is supporting context for acceptance, not proof of it; runtime verification is separate. Example: The verify node's acceptance evidence must show a real input/action and its observable output, tied to the current diff's revision.

Traceability​

What it is: The chain from a work item to the code and tests that satisfy it: work item → requirement/use case → acceptance criteria → change evidence → tests → pull request, using the identifiers your task and spec already carry (FR-###, UC-###, issue number). See Traceability. What it is not: Not a new tracking system or source-code comment convention Asterweave asks you to adopt. Example: A PR body referencing UC-024 and the GitHub issue it closes.